From 73b16af8feec390afbabd9356d6e5e83c0390838 Mon Sep 17 00:00:00 2001 From: Bjørn Mork Date: Fri, 15 May 2015 10:20:47 +0200 Subject: busybox: imported from http://www.busybox.net/downloads/busybox-1.13.3.tar.bz2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Bjørn Mork --- docs/Serial-Programming-HOWTO.txt | 424 +++++ docs/autodocifier.pl | 307 ++++ docs/busybox.net/FAQ.html | 1146 +++++++++++++ docs/busybox.net/about.html | 24 + docs/busybox.net/busybox-growth.ps | 404 +++++ docs/busybox.net/copyright.txt | 30 + docs/busybox.net/developer.html | 69 + docs/busybox.net/download.html | 60 + docs/busybox.net/fix.html | 15 + docs/busybox.net/footer.html | 51 + docs/busybox.net/header.html | 91 + docs/busybox.net/images/back.png | Bin 0 -> 322 bytes docs/busybox.net/images/busybox.jpeg | Bin 0 -> 9023 bytes docs/busybox.net/images/busybox.png | Bin 0 -> 34014 bytes docs/busybox.net/images/busybox1.png | Bin 0 -> 10913 bytes docs/busybox.net/images/busybox2.jpg | Bin 0 -> 8204 bytes docs/busybox.net/images/busybox3.jpg | Bin 0 -> 3292 bytes docs/busybox.net/images/dir.png | Bin 0 -> 309 bytes docs/busybox.net/images/donate.png | Bin 0 -> 807 bytes docs/busybox.net/images/fm.mini.png | Bin 0 -> 7708 bytes docs/busybox.net/images/gfx_by_gimp.png | Bin 0 -> 3955 bytes docs/busybox.net/images/ltbutton2.png | Bin 0 -> 6798 bytes docs/busybox.net/images/osuosl.png | Bin 0 -> 8683 bytes docs/busybox.net/images/sdsmall.png | Bin 0 -> 1593 bytes docs/busybox.net/images/text.png | Bin 0 -> 307 bytes docs/busybox.net/images/valid-html401.png | Bin 0 -> 1950 bytes docs/busybox.net/images/vh40.gif | Bin 0 -> 906 bytes docs/busybox.net/images/written.in.vi.png | Bin 0 -> 4394 bytes docs/busybox.net/index.html | 1 + docs/busybox.net/license.html | 99 ++ docs/busybox.net/links.html | 19 + docs/busybox.net/lists.html | 46 + docs/busybox.net/news.html | 216 +++ docs/busybox.net/oldnews.html | 2214 ++++++++++++++++++++++++ docs/busybox.net/products.html | 164 ++ docs/busybox.net/screenshot.html | 75 + docs/busybox.net/shame.html | 82 + docs/busybox.net/sponsors.html | 56 + docs/busybox.net/subversion.html | 51 + docs/busybox.net/tinyutils.html | 86 + docs/busybox_footer.pod | 256 +++ docs/busybox_header.pod | 83 + docs/cgi/cl.html | 46 + docs/cgi/env.html | 149 ++ docs/cgi/in.html | 33 + docs/cgi/interface.html | 29 + docs/cgi/out.html | 126 ++ docs/contributing.txt | 449 +++++ docs/ctty.htm | 476 +++++ docs/draft-coar-cgi-v11-03-clean.html | 2674 +++++++++++++++++++++++++++++ docs/ifupdown_design.txt | 44 + docs/keep_data_small.txt | 216 +++ docs/mdev.txt | 127 ++ docs/new-applet-HOWTO.txt | 182 ++ docs/nofork_noexec.txt | 79 + docs/sigint.htm | 627 +++++++ docs/style-guide.txt | 714 ++++++++ docs/tar_pax.txt | 239 +++ 58 files changed, 12279 insertions(+) create mode 100644 docs/Serial-Programming-HOWTO.txt create mode 100755 docs/autodocifier.pl create mode 100644 docs/busybox.net/FAQ.html create mode 100644 docs/busybox.net/about.html create mode 100644 docs/busybox.net/busybox-growth.ps create mode 100644 docs/busybox.net/copyright.txt create mode 100644 docs/busybox.net/developer.html create mode 100644 docs/busybox.net/download.html create mode 100644 docs/busybox.net/fix.html create mode 100644 docs/busybox.net/footer.html create mode 100644 docs/busybox.net/header.html create mode 100644 docs/busybox.net/images/back.png create mode 100644 docs/busybox.net/images/busybox.jpeg create mode 100644 docs/busybox.net/images/busybox.png create mode 100644 docs/busybox.net/images/busybox1.png create mode 100644 docs/busybox.net/images/busybox2.jpg create mode 100644 docs/busybox.net/images/busybox3.jpg create mode 100644 docs/busybox.net/images/dir.png create mode 100644 docs/busybox.net/images/donate.png create mode 100644 docs/busybox.net/images/fm.mini.png create mode 100644 docs/busybox.net/images/gfx_by_gimp.png create mode 100644 docs/busybox.net/images/ltbutton2.png create mode 100644 docs/busybox.net/images/osuosl.png create mode 100644 docs/busybox.net/images/sdsmall.png create mode 100644 docs/busybox.net/images/text.png create mode 100644 docs/busybox.net/images/valid-html401.png create mode 100644 docs/busybox.net/images/vh40.gif create mode 100644 docs/busybox.net/images/written.in.vi.png create mode 100644 docs/busybox.net/index.html create mode 100644 docs/busybox.net/license.html create mode 100644 docs/busybox.net/links.html create mode 100644 docs/busybox.net/lists.html create mode 100644 docs/busybox.net/news.html create mode 100644 docs/busybox.net/oldnews.html create mode 100644 docs/busybox.net/products.html create mode 100644 docs/busybox.net/screenshot.html create mode 100644 docs/busybox.net/shame.html create mode 100644 docs/busybox.net/sponsors.html create mode 100644 docs/busybox.net/subversion.html create mode 100644 docs/busybox.net/tinyutils.html create mode 100644 docs/busybox_footer.pod create mode 100644 docs/busybox_header.pod create mode 100644 docs/cgi/cl.html create mode 100644 docs/cgi/env.html create mode 100644 docs/cgi/in.html create mode 100644 docs/cgi/interface.html create mode 100644 docs/cgi/out.html create mode 100644 docs/contributing.txt create mode 100644 docs/ctty.htm create mode 100644 docs/draft-coar-cgi-v11-03-clean.html create mode 100644 docs/ifupdown_design.txt create mode 100644 docs/keep_data_small.txt create mode 100644 docs/mdev.txt create mode 100644 docs/new-applet-HOWTO.txt create mode 100644 docs/nofork_noexec.txt create mode 100644 docs/sigint.htm create mode 100644 docs/style-guide.txt create mode 100644 docs/tar_pax.txt (limited to 'docs') 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, + + 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 + 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 . 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 + + 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 + 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 . 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 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/(?/sxg; + } + my @f0 = + map { $_ !~ /^\s/ && s/(?/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, +F. This was tedious and error-prone, so it was +decided that F 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 is one such script. It is based on a script by +Erik Andersen which was in turn based on a +script by Mark Whitley + +=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 + +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 + +=item B + +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 + +=item B + +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. I + +=item B + +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 + +=back + +=head1 FILES + +F + +=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 + +=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 @@ + + +

Frequently Asked Questions

+ +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, + +

General questions

+
    +
  1. How can I get started using BusyBox?
    2. +
  2. How do I configure busybox?
    3. +
  3. How do I build BusyBox with a cross-compiler?
    4. +
  4. How do I build a BusyBox-based system?
    5. +
  5. Which Linux kernel versions are supported?
    6. +
  6. Which architectures does BusyBox run on?
    7. +
  7. Which C libraries are supported?
    8. +
  8. Can I include BusyBox as part of the software on my device?
    9. +
  9. Where can I find other small utilities since busybox does not include the features I want?
    10. +
  10. 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 Right Now!
    11. +
  11. I need help with BusyBox! What should I do?
    12. +
  12. 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?
    13. +
+ +

Troubleshooting

+
    +
  1. I think I found a bug in BusyBox! What should I do?!
    2. +
  2. I'm using an ancient version from the dawn of time and something's broken. Can you backport fixes for free?
    3. +
  3. Busybox init isn't working!
    4. +
  4. I can't configure busybox on my system.
    5. +
  5. Why do I keep getting "sh: can't access tty; job control turned off" errors? Why doesn't Control-C work within my shell?
    6. +
+ +

Misc. questions

+
    +
  1. How do I change the time zone in busybox?
    2. +
+ +

Programming questions

+
    +
  1. What are the goals of busybox?
    2. +
  2. What is the design of busybox?
    3. +
  3. How is the source code organized? + +
    4. +
  4. I want to make busybox even smaller, how do I go about it?
    5. +
  5. Adding an applet to busybox
    6. +
  6. What standards does busybox adhere to?
    7. +
  7. Portability.
    8. +
  8. Tips and tricks. + +
    9. +
  9. Who are the BusyBox developers?
    10. +
+ + +
+

General questions

+ +
+

How can I get started using BusyBox?

+ +

If you just want to try out busybox without installing it, download the + tarball, extract it, run "make defconfig", and then run "make". +

+

+ 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. +

+

+ 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. +

+

+ BusyBox also has a feature called the + "standalone shell", 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.) +

+

+ A typical indication that you set CONFIG_BUSYBOX_EXEC_PATH to proc but + forgot to mount proc is: +

+$ /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
+
+ +
+

How do I configure busybox?

+ +

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". +

+ +

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. +

+ +

The most important busybox configurators are:

+ +
    +

  • make defconfig - 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.

    • +

  • make allnoconfig - 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.

    • +

  • make menuconfig - Interactively modify a .config file through a +multi-level menu interface. Use this after one of the previous two.

    • +
+ +

Some other configuration options are:

+
    +

  • make oldconfig - Update an old .config file for a newer version +of busybox.

    • +

  • make allyesconfig - 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.

    • +

  • make allbareconfig - Select all applets but disable all sub-features +within each applet. More build coverage testing.

    • +

  • make randconfig - Create a random configuration for test purposes.

    • +
+ +

Menuconfig modifies your .config file through an interactive menu where you can enable or disable + busybox features, and get help about each feature. + +

+ 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.) +

+ +
+

How do I build BusyBox with a cross-compiler?

+ +

+ To build busybox with a cross-compiler, specify CROSS_COMPILE=<prefix>. +

+

+ 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: +

+
+   make CROSS_COMPILE=arm-linux-uclibcgnueabi-
+
+

+ Alternatively CROSS_COMPILE can be set in the environment. + Default value for CROSS_COMPILE is not to prefix executables. +

+

+ To store the cross-compiler in your .config, set the variable + CONFIG_CROSS_COMPILER_PREFIX accordingly in menuconfig or by + editing the .config file. +

+ +
+

How do I build a BusyBox-based system?

+ +

+ 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. +

+

+ 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 Linux + BootDisk Howto, or for a more theoretical approach try + From + PowerUp to Bash Prompt. +

+

+ To learn how to build a working Linux system entirely from source code, + the place to go is the Linux + From Scratch project. They have an entire book of step-by-step + instructions you can + read online + or + download. + 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.) +

+

+ If you want an automated yet customizable system builder which produces + a BusyBox and uClibc based system, try + buildroot, 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. +

+ +
+

Which Linux kernel versions are supported?

+ +

+ 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). +

+ +
+

Which architectures does BusyBox run on?

+ +

+ 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. +

+

+ With 2.6.x kernels, module loading support should work on all architectures. +

+ +
+

Which C libraries are supported?

+ +

+ 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. +

+

+ 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. +

+

+ Some BusyBox applets have been built and run under a combination + of newlib and libgloss (see + this thread). + This is still experimental, but may be supported in a future release. +

+ +
+

Can I include BusyBox as part of the software on my device?

+ +

+ Yes. As long as you fully comply + with the generous terms of the GPL BusyBox license you can ship BusyBox + as part of the software on your device. +

+ +
+

Where can I find other small utilities since busybox + does not include the features i want?

+ +

+ we maintain such a list on this site! +

+ +
+

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 Right Now!

+ +

+ 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. + +

+

I need help with BusyBox! What should I do?

+ +

+ If you find that you need help with BusyBox, you can ask for help on the + BusyBox mailing list at busybox@busybox.net.

+ +

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 + web archive of + daily logs of the #uclibc IRC channel going back to 2002. +

+ +

+ 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. +

+ +

+ 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. +

+ +
+

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?

+ +

+ 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. +

+ +
+

Troubleshooting

+ +
+

I think I found a bug in BusyBox! What should I do?

+ +

+ If you simply need help with using or configuring BusyBox, please submit a + detailed description of your problem to the BusyBox mailing list at busybox@busybox.net. + 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... +

+ +

+ 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 + BusyBox Bug + and Patch Tracking System to submit a detailed explanation and we'll + get to it as soon as we can. +

+ +

+ 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.) +

+ +
+

I'm using an ancient version from the dawn of time and something's broken. Can you backport fixes for free?

+ +

Variants of this one get asked a lot.

+ +

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.

+ +

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.

+ +

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.

+ +

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.

+ +

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.

+ +

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.

+ +
+

Busybox init isn't working!

+ +

+ 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: +

+
+#include <stdio.h>
+
+int main(int argc, char *argv)
+{
+  printf("Hello world!\n");
+  sleep(999999999);
+}
+
+ +

+ 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. +

+ +

+ Once you've got it working statically linked, try getting it to work + dynamically linked. Then read the FAQ entry How + do I build a BusyBox-based system?, and the + documentation for BusyBox + init. +

+ +
+

I can't configure busybox on my system.

+ +

+ 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: +

+ +
+  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"
+
+ +

Then you can run "make defconfig" or "make menuconfig" normally.

+ +
+

Why do I keep getting "sh: can't access tty; job control turned off" errors? Why doesn't Control-C work within my shell?

+ +

+ 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 REALLY 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... +

+ +
+

Misc. questions

+ +
+

How do I change the time zone in busybox?

+ +

Busybox has nothing to do with the timezone. Please consult your libc +documentation. (http://google.com/search?q=uclibc+glibc+timezone).

+ +
+

Development

+ +
+

What are the goals of busybox?

+ +

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 standards +compliant, minimize run-time memory usage (heap and stack), run fast, and +take over the world.

+ +
+

What is the design of busybox?

+ +

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 getting started in the +FAQ for more information on usage, and the +busybox documentation for a list of symlink names and what they do.) + +

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.

+ +

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.

+ + + +
+

The applet directories

+ +

The directory "applets" contains the busybox startup code (applets.c and +busybox.c), and several subdirectories containing the code for the individual +applets.

+ +

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.

+ +

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().

+ +

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 getting started in the +FAQ for more information on these alternate usage mechanisms, which are +just different ways to reach the relevant APPLET_main() function.

+ +

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.

+ +

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 +adding an applet to busybox for more +information.

+ +
+

libbb

+ +

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.

+ +

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.

+ +
+

I want to make busybox even smaller, how do I go about it?

+ +

+ 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). +

+ +

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.) +

+ +

The "make bloatcheck" 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 "make baseline". + (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. +

+

+ 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). +

+

+ The "make sizes" 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. +

+

+ 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. +

+ +
+

Adding an applet to busybox

+ +

To add a new applet to busybox, first pick a name for the applet and +a corresponding CONFIG_NAME. Then do this:

+ +
    +
  • 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.
    • + +
  • 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.
    • + +
  • 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.)
    • + +
  • 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.)
    • + +
  • 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).
    • + +
  • Run menuconfig, switch your applet on, compile, test, and fix the +bugs. Be sure to try both "allyesconfig" and "allnoconfig" (and +"allbareconfig" if relevant).
    • + +
+ +
+

What standards does busybox adhere to?

+ +

The standard we're paying attention to is the "Shell and Utilities" +portion of the Open +Group Base Standards (also known as the Single Unix Specification version +3 or SUSv3). Note that paying attention isn't necessarily the same thing as +following it.

+ +

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.

+ +

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.

+ +

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.

+ +
+

Portability.

+ +

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.

+ +

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.

+ +

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.

+ +

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 +trimming +down the 2.6 kernel.) Older gcc versions than that are uninteresting since +we now use c99 features, although +tcc might be worth a +look.

+ +

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).

+ +

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: the 86open +project. 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 AIX, Solaris, and +FreeBSD) +have all either grown Linux support or folded.

+ +

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.

+ +

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.

+ +
+

Programming tips and tricks.

+ +

Various things busybox uses that aren't particularly well documented +elsewhere.

+ +
+

Encrypted Passwords

+ +

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:

+
+  $type$salt$encrypted_password
+
+ +

The "type" indicates which encryption algorithm to use: 1 for MD5 and 2 for SHA1.

+ +

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.)

+ +

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.

+ +

The third field is the encrypted password (plus the salt). For md5 this +is 22 bytes.

+ +

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.

+ +

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).

+ +
+

Fork and vfork

+ +

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.)

+ +

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.

+ +

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.

+ +

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.)

+ +

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.)

+ +

So with a primitive or missing MMU, fork() is just not a good idea.

+ +

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.

+ +

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.) + +

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.

+ +

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.)

+ +

(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.)

+ +
+

Short reads and writes

+ +

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:

+ +
while true; do echo hello; sleep 1; done | tee out.txt
+ +

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.)

+ +

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...)

+ +

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 rfc 896 +for Nagle's algorithm, 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.)

+ +
+

Memory used by relocatable code, PIC, and static linking.

+ +

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.

+ +

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.

+ +

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.

+ +

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.

+ +

For more on this topic, here's Rich Felker:

+
+

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.

+ +

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.

+ +

The ELF dynamic linker has its own data segment, adding one or more +dirty pages. I believe it also performs relocations on itself.

+ +

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.

+ +

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.

+ +

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).

+
+ +
+

Including kernel headers

+ +

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.

+ +

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.

+ +

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.

+ +

The BusyBox developers spent two years 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. +

+ +

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.

+ +
+

Who are the BusyBox developers?

+ +

The following login accounts currently exist on busybox.net. (I.E. these +people can commit patches +into subversion for the BusyBox, uClibc, and buildroot projects.)

+ +
+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
+
+ +

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:

+ +
+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
+
+ + +
+
+
+ + 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 @@ + + +

BusyBox: The Swiss Army Knife of Embedded Linux

+ +

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.

+ +

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.

+ +

BusyBox is maintained by +Denys Vlasenko, +and licensed under the GNU GENERAL PUBLIC LICENSE +version 2.

+ + 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 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 @@ + + +

Morris Dancing

+ +

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 (Rob +Landley for BusyBox, or Erik +Andersen for uClibc) for an account.

+ +

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.

+ +

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 ssh-keygen -t dsa and hitting enter at the prompts. This +will create the files ~/.ssh/id_dsa and ~/.ssh/id_dsa.pub +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 .ssh/authorized_keys file.)

+ +

Note that if you would prefer to keep your communications with us +private, you can encrypt your email using +Rob's public key or +Erik's public +key.

+ +

Once you are setup with an account, you will need to use your account to +checkout a copy of BusyBox from Subversion:

+ +

svn checkout svn+ssh://username@busybox.net/svn/trunk/busybox

+

or

+

svn checkout svn+ssh://username@uclibc.org/svn/trunk/uclibc

+ +

You must change username to your own username, or omit +it if it's the same as your local username.

+ +

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:

+ +
+svn diff
+svn status
+svn revert
+EDITOR=vi svn commit
+svn log -v -r PREV:HEAD
+svn help
+
 + +

For additional detail on how to use Subversion, please visit the +the Subversion website. +You might also want to read online or buy a copy of the Subversion Book...

+ +

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".

+ + 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 @@ + + + + +

Download

+ +

+Source for the latest release can always be +downloaded from http://www.busybox.net/downloads/. + +

+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. +

+Latest releases and patch directories for each branch: +
+1.10.1, +patches, +
+1.9.2, +patches, +
+1.8.3, +patches, +
+1.7.5, +patches, +
+1.6.2, +patches, +
+1.5.2, +patches, +
+1.4.2, +patches, +
+1.3.2, +patches. + +

+You can also obtain Daily Snapshots of +the latest development source tree for those wishing to follow BusyBox development, +but cannot or do not wish to use Subversion (svn). + +

+ + + 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 @@ + + +

How to get your patch added to "hot fixes"

+ +

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 + the mailing list. +

+ +
+
+
+ + 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 @@ + + + + + + + +
+ + + + + + + + + + + +
+ + + Copyright © 1999-2008 Erik Andersen +
+ Mail all comments, insults, suggestions and bribes to +
+ Denys Vlasenko vda.linux@googlemail.com
+ + + 		+ This site created with the vi editor + + This site is kindly hosted by OSL +
+ + + + 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 @@ + + + + + + BusyBox + + + + + + + + + + + + + + + +
+
+ + + + +
BUSYBOX
+
+ + BusyBox
+
+ About + + Documentation + + Get BusyBox + + Development + +

Links +

+

Developer Pages +

+		 + diff --git a/docs/busybox.net/images/back.png b/docs/busybox.net/images/back.png new file mode 100644 index 0000000..7992386 Binary files /dev/null and b/docs/busybox.net/images/back.png differ diff --git a/docs/busybox.net/images/busybox.jpeg b/docs/busybox.net/images/busybox.jpeg new file mode 100644 index 0000000..37edc96 Binary files /dev/null and b/docs/busybox.net/images/busybox.jpeg differ diff --git a/docs/busybox.net/images/busybox.png b/docs/busybox.net/images/busybox.png new file mode 100644 index 0000000..b1eb92f Binary files /dev/null and b/docs/busybox.net/images/busybox.png differ diff --git a/docs/busybox.net/images/busybox1.png b/docs/busybox.net/images/busybox1.png new file mode 100644 index 0000000..4d3126a Binary files /dev/null and b/docs/busybox.net/images/busybox1.png differ diff --git a/docs/busybox.net/images/busybox2.jpg b/docs/busybox.net/images/busybox2.jpg new file mode 100644 index 0000000..abf8f06 Binary files /dev/null and b/docs/busybox.net/images/busybox2.jpg differ diff --git a/docs/busybox.net/images/busybox3.jpg b/docs/busybox.net/images/busybox3.jpg new file mode 100644 index 0000000..0fab84c Binary files /dev/null and b/docs/busybox.net/images/busybox3.jpg differ diff --git a/docs/busybox.net/images/dir.png b/docs/busybox.net/images/dir.png new file mode 100644 index 0000000..1d633ce Binary files /dev/null and b/docs/busybox.net/images/dir.png differ diff --git a/docs/busybox.net/images/donate.png b/docs/busybox.net/images/donate.png new file mode 100644 index 0000000..b55621b Binary files /dev/null and b/docs/busybox.net/images/donate.png differ diff --git a/docs/busybox.net/images/fm.mini.png b/docs/busybox.net/images/fm.mini.png new file mode 100644 index 0000000..c0883cd Binary files /dev/null and b/docs/busybox.net/images/fm.mini.png differ diff --git a/docs/busybox.net/images/gfx_by_gimp.png b/docs/busybox.net/images/gfx_by_gimp.png new file mode 100644 index 0000000..d583140 Binary files /dev/null and b/docs/busybox.net/images/gfx_by_gimp.png differ diff --git a/docs/busybox.net/images/ltbutton2.png b/docs/busybox.net/images/ltbutton2.png new file mode 100644 index 0000000..9bad949 Binary files /dev/null and b/docs/busybox.net/images/ltbutton2.png differ diff --git a/docs/busybox.net/images/osuosl.png b/docs/busybox.net/images/osuosl.png new file mode 100644 index 0000000..b00b500 Binary files /dev/null and b/docs/busybox.net/images/osuosl.png differ diff --git a/docs/busybox.net/images/sdsmall.png b/docs/busybox.net/images/sdsmall.png new file mode 100644 index 0000000..b102450 Binary files /dev/null and b/docs/busybox.net/images/sdsmall.png differ diff --git a/docs/busybox.net/images/text.png b/docs/busybox.net/images/text.png new file mode 100644 index 0000000..6034f89 Binary files /dev/null and b/docs/busybox.net/images/text.png differ diff --git a/docs/busybox.net/images/valid-html401.png b/docs/busybox.net/images/valid-html401.png new file mode 100644 index 0000000..ec9bc0c Binary files /dev/null and b/docs/busybox.net/images/valid-html401.png differ diff --git a/docs/busybox.net/images/vh40.gif b/docs/busybox.net/images/vh40.gif new file mode 100644 index 0000000..c5e9402 Binary files /dev/null and b/docs/busybox.net/images/vh40.gif differ diff --git a/docs/busybox.net/images/written.in.vi.png b/docs/busybox.net/images/written.in.vi.png new file mode 100644 index 0000000..84f59bc Binary files /dev/null and b/docs/busybox.net/images/written.in.vi.png differ 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 @@ + 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 @@ + + +

+

BusyBox is licensed under the GNU General Public License, version 2

+ +

BusyBox is licensed under the +GNU General Public License 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.)

+ +

A complete copy of the license text is included in the file LICENSE in +the BusyBox source code.

+ +

Anyone thinking of shipping BusyBox as part of a +product 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 Frequently +Asked Questions about the GPL.

+ +

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.

+ +

A note on GPL versions

+ +

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.

+ +

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.

+ +

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.)

+ +

To summarize: every version of BusyBox may be distributed under the terms of +GPL version 2. New versions (after 1.2.2) may only 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.

+ +

License enforcement

+ +

BusyBox's copyrights are enforced by the Software Freedom Law Center +(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 The Hall of Shame, +but these days we find it much more effective to hand them over to the +lawyers.)

+ +

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.

+ +

A Good Example

+ +

These days, Linksys 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 + +distributing the firmware for their WRT54G Router. +Following their example would be a fine way to ensure that you +have also fulfilled your licensing obligations.

+ + + 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 @@ + + +

Related Sites

+ +
uClibc.org +
uClibc++ + +
buildroot +
Scratchbox +
OpenEmbedded +
uCdot +
LinuxDevices +
Slashdot +
Freshmeat +
Linux Today +
Linux Weekly News +
Linux HOWTOs + + 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 @@ + + + + + +

Mailing List Information

+BusyBox has a mailing list for discussion and +development. You can subscribe by visiting +this page. +Only subscribers to the BusyBox mailing list are allowed to post +to this list. + +

+There is also a mailing list for active developers +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 +this page. +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... + +

+ + +

Search the List Archives

+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... +

+ +

+
+ + + +
+ +
+Google +
+
+
+ + + + 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 @@ + + +
    + +
  • +

    We want to thank the following companies which are providing support for the BusyBox project: +

    +

    +
    • + +
  • 28 September 2008 -- BusyBox 1.12.1 (stable), BusyBox 1.11.3 (stable) +

    BusyBox 1.12.1. + (svn, + patches, + how to add a patch)

    +

    BusyBox 1.11.3. + (svn, + patches, + how to add a patch)

    +

    + Bugfix-only releases for 1.11.x and 1.12.x branches. +

    +
    • + +
  • 21 August 2008 -- BusyBox 1.12.0 (unstable), BusyBox 1.11.2 (stable) +

    BusyBox 1.12.0. + (svn, + patches, + how to add a patch)

    +

    BusyBox 1.11.2. + (svn, + patches, + how to add a patch)

    + +

    Sizes of busybox-1.11.2 and busybox-1.12.0 (with equivalent config, static uclibc build):

    +   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
+
    + +

    New applets: rdev (Grant Erickson), setfont, showkey (both by Vladimir) + +

    Most significant changes since previous release (please report any regression): +

      +
    • ash: bash compat: "shift $BIGNUM" is equivalent to "shift 1"
      • +
    • ash: dont allow e.g. exec <&10 to attach to script's fd!
      • +
    • ash: fix a bug where redirection fds were not closed afterwards. optimize close+fcntl(DUPFD) into dup2
      • +
    • ash: fix segfault in "command -v"
      • +
    • ash: fix very weak $RANDOM generator
      • +
    • ash: prevent exec NN>&- from closing fd used for script reading
      • +
    • ash: teach ash about 123>file. It could take only 0..9 before
      • +
    • hush: fix a case where "$@" must expand to no word at all
      • +
    • hush: fix mishandling of a'b'c=fff as assignments. They are not
      • +
    • hush: fix non-detection of builtins and applets in "v=break; ...; $v; ..." case
      • +
    • hush: fix "while false; ..." exitcode; add testsuites
      • +
    • hush: support "case...esac" statements (~350 bytes of code)
      • +
    • hush: support "break [N]" and "continue [N]" statements
      • +
    • hush: support "for if in do done then; do echo $if; done" case
      • +
    • hush: support "for v; do ... done" syntax (implied 'in "$@"')
      • +
    • hush: support $_NUMBERS variable names
      • +
    • libbb: unified config parser (by Vladimir). This change affected many applets
      • +
    + +

    Other changes: +

      +
    • libbb: dump: do not use uninitialized memory (closes bug 4364)
      • +
    • libbb: fix bb_strtol[l]'s check for "-" (closes bug 4174)
      • +
    • libbb: fix --help to not affect "test --help"
      • +
    • libbb: fix mishandling of "all argv are opts" in getopt32()
      • +
    • libbb: getopt32() should not ever touch argv[0] (even read)
      • +
    • libbb: introduce and use xrealloc_vector
      • +
    • libbb: [x]fopen_for_{read,write} introduced and used (by Vladimir)
      • +
    • lineedit: fix use-after-free
      • +
    • libunarchive: refactor handling of archived files. "tar f file.tar.lzma" now works too
      • +
    • bb_strtoXXX: close bug 4174 (potential use of buf[-1])
      • +
    • open_transformer: don't leak file descriptor
      • +
    • open_transformer: fix bug of calling exit instead of _exit
      • +
    • arp: without -H type, assume "ether" (closes bug 4564)
      • +
    • ar: reuse existing ar unpacking code
      • +
    • awk: fix a case with multiple -f options. Simplify -f file reading.
      • +
    • build system: introduce and use FAST_FUNC: regparm on i386, otherwise no-op
      • +
    • bunzip2: fix an uncompression error (by Rob Landley rob AT landley.net)
      • +
    • b[un]zip2, g[un]zip: unlink destination if -f is given (closes bug 3854)
      • +
    • comm: almost total rewrite
      • +
    • cpio: fix -m to actually work as expected (by Pascal Bellard)
      • +
    • cpio: internalize archive_xread_all_eof, add a few paranoia checks for corrupted cpio files
      • +
    • cpio: make long opts depend only on ENABLE_GETOPT_LONG
      • +
    • cpio: on unpack, limit filename length to 8k
      • +
    • cpio: support some long options
      • +
    • crond: use execlp instead of execl
      • +
    • cut: fix buffer overflow (closes bug 4544)
      • +
    • envdir: fix "envdir" (no params at all) and "envdir dir" cases
      • +
    • findfs: make it use setuid-ness of busybox binary
      • +
    • fsck: use getmntent_r instead of open-coded parsing (by Vladimir)
      • +
    • fuser: a bit of safety in scanf
      • +
    • grep: option to use GNU regex matching instead of POSIX one. This fixes problems with NULs in files being scanned, but costs +800 bytes
      • +
    • halt: signal init regardless of ENABLE_INIT
      • +
    • httpd: add homedir directive specially for (and by) Walter Harms wharms AT bfs.de
      • +
    • ifupdown: /etc/network/interfaces can have comments with leading blanks
      • +
    • ifupdown: fixes for custom MAC address (by Wade Berrier wberrier AT gmail.com)
      • +
    • ifupdown: fixes for shutdown of DHCP-managed interfaces (by Wade Berrier wberrier AT gmail.com)
      • +
    • inetd: do not trash errno in signal handlers; in CHLD handler, stop looping through services when pid is found
      • +
    • insmod: users report that "|| defined(__powerpc__)" is missing
      • +
    • install: do not chown intermediate directories with install -d (by Natanael Copa)
      • +
    • install: fix long option not taking params (closes bug 4584)
      • +
    • lpd,lpr: send/receive ACKs after filenames, not only after file bodies
      • +
    • ls: fix a bug where we may use uninintialized variable
      • +
    • man: add handling of "man links", by Ivana Varekova varekova AT redhat.com
      • +
    • man: fix a case when a full pathname to manpage is given
      • +
    • man: fix inverted cat/man bool variable
      • +
    • man: fix missed NULL termination of an array
      • +
    • man: mimic "no manual entry for 'bogus'" message and exitcode
      • +
    • man: support cat pages too (by Jason Curl jcurlnews AT arcor.de)
      • +
    • man: teach it to use .lzma if requested by .config
      • +
    • mdev: check for "/block/" substring for block dev detection
      • +
    • mdev: do not complain if mdev.conf does not exist
      • +
    • mdev: if device was moved at creation, at removal correctly remove it from moved location and also remove symlinks to it
      • +
    • mdev: support for serializing hotplug
      • +
    • mdev, init: use shared code for fd sanitization
      • +
    • mkdir: fix "uname 0222; mkdir -p foo/bar" case (by Doug Graham dgraham AT nortel.com)
      • +
    • modprobe: support for /etc/modprobe.d (by Timo Teras)
      • +
    • modprobe: use buffering line reads (fgets()) instead of reads()
      • +
    • modutils: optional modprobe-small (by Vladimir), 15kb smaller than standard one
      • +
    • mount: support for "-o mand" and "[no]relatime"
      • +
    • mount: support nfs mount option "nordiplus" (by Octavian Purdila opurdila AT ixiacom.com)
      • +
    • mount: support "relatime" / "norelatime"
      • +
    • mount: testsuite for "-o mand"
      • +
    • msh: fix "while... continue; ..." (closes bug 3884)
      • +
    • mv: fix a case when we move dangling symlink across mountpoints
      • +
    • netstat: optional -p support (by L. Gabriel Somlo somlo AT cmu.edu)
      • +
    • nmeter: fix read past the end of a buffer (closes bug 4594)
      • +
    • od, hexdump: fix bug where xrealloc may move pointer, leaving other pointers dangling (closes bug 4104)
      • +
    • pidof/killall: allow find_pid_by_name to find running processes started as scripts_with_name_longer_than_15_bytes.sh (closes bug 4054)
      • +
    • printf: do not print garbage on "%Ld" (closes bug 4214)
      • +
    • printf: fix %b, fix several bugs in %*.*, fix compat issues with aborting too early, support %zd; expand testsuite
      • +
    • printf: protect against bogus format specifiers (closes bug 4184)
      • +
    • sendmail: updates from Vladimir:
      • +
    • sendmail: do not discard all headers
      • +
    • sendmail: do not ignore CC; accept to: and cc: case-insensitively. +20 bytes
      • +
    • sendmail: fixed mail recipient address
      • +
    • sendmail: fixed SEGV if sender address is missed
      • +
    • sendmail: use HOSTNAME instead of HOST when no server is explicitly specified
      • +
    • sleep: if FANCY && DESKTOP, support fractional seconds, minutes, hours and so on (coreutils compat)
      • +
    • ssd: CLOSE_EXTRA_FDS in MMU case too
      • +
    • ssd: do not stat -x EXECUTABLE, it is not needed anymore
      • +
    • ssd: fix -a without -x case
      • +
    • ssd: use $PATH
      • +
    • tar: fix handling of tarballs with symlinks with size field != 0
      • +
    • tar: handle autodetection for tiny .tar.gz files too, simplify autodetection
      • +
    • taskset: fix some careless code in both fancy and non-fancy cases. -5 bytes for fancy, +5 for non-fancy
      • +
    • tee: fix infinite looping on open error (echo asd | tee "")
      • +
    • tee: "-" is a name for stdout, handle it that way
      • +
    • telnetd: fix issue file printing
      • +
    • test: fix parser to prefer binop over unop, as coreutils does
      • +
    • testsuite: uniformly use $ECHO with -n -e
      • +
    • time: don't segfault with no arguments
      • +
    • touch: support -r REF_FILE if ENABLE_DESKTOP (needed for blackfin compile)
      • +
    • tr: fix "access past the end of a string" bug 4354
      • +
    • tr: fix "tr [=" case (closes bug 4374)
      • +
    • tr: fix yet another access past the end of a string (closes bug 4374)
      • +
    • unlzma: fix memory leak (by Pascal Bellard)
      • +
    • vi: fix reversed checks for underflow
      • +
    • vi: using array data after it fell out of scope is stupid
      • +
    • xargs: fix -e default to match newer GNU xargs, add SUS mandated -E (closes bug 4414)
      • +
    • other fixes and code size reductions in many applets
      • +
    +

    + The email address gpl@busybox.net is the recommended way to contact + the Software Freedom Law Center to report BusyBox license violations. +

    + +
  • 12 July 2008 -- BusyBox 1.11.1 (stable) +

    BusyBox 1.11.1. + (svn, + patches, + how to add a patch)

    +

    + Bugfix-only release for 1.11.x branch. It contains fixes for awk, + bunzip2, cpio, ifupdown, ip, man, start-stop-daemon, uname and vi. +

    +
    • + +
  • 11 July 2008 -- HOWTO is updated +

    + + "How to build static busybox for i486-linux-uclibc" is updated + and tested on a fresh Fedora 9 install. Please report if it doesn't + work for you. +

    +
    • + + + +
  • Old News

    + Click here to read older news +

    +
    • + +
+ + + 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 @@ + + +

News archive

+ +
    + +
  • 25 June 2008 -- BusyBox 1.11.0 (unstable), BusyBox 1.10.4 (stable) +

    BusyBox 1.11.0. + (svn, + patches, + how to add a patch)

    +

    BusyBox 1.10.4. + (svn, + patches, + how to add a patch)

    +

    Sizes of busybox-1.10.4 and busybox-1.11.0 (with equivalent config, static uclibc build):

    +   text    data     bss     dec     hex filename
+ 800675     636    7080  808391   c55c7 busybox-1.10.4
+ 798392     611    6900  805903   c4c0f busybox-1.11.0
+
    + +

    New applets: inotify (Vladimir Dronnikov), man (Ivana Varekova), + fbsplash (Michele Sanges), depmod (Bernhard Reutner-Fischer) + +

    Changes since previous release: +

      +
    • build system: reinstate CONFIG_CROSS_COMPILE_PREFIX
      • +
    • ash: optional bash compatibility features added; other fixes
      • +
    • hush: lots and lots of fixes
      • +
    • msh: fix the case where the file has exec bit but can't be run directly (runs "$SHELL file" instead)
      • +
    • msh: fix exit codes when command is not found or can't be execed
      • +
    • udhcpc: added workaround for buggy kernels
      • +
    • mount: fix mishandling of proto=tcp/udp
      • +
    • diff: make it work on non-seekable streams
      • +
    • openvt: made more compatible with "standard" one
      • +
    • mdev: fix block/char device detection
      • +
    • ping: add -w, -W support (James Simmons)
      • +
    • crond: add handling of "MAILTO=user" lines
      • +
    • start-stop-daemon: make --exec follow symlinks (Joakim Tjernlund)
      • +
    • date: make it accept ISO date format
      • +
    • echo: fix echo -e -n "msg\n\0" (David Pinedo)
      • +
    • httpd: fix several bugs triggered by relative path in -h DIR
      • +
    • printf: fix printf -%s- foo, printf -- -%s- foo
      • +
    • syslogd: do not error out on missing files to rotate
      • +
    • ls: support Unicode in names
      • +
    • ip: support for the LOWER_UP flag (Natanael Copa)
      • +
    • mktemp: make argument optional (coreutil 6.12 compat)
      • +
    • libiproute: fix option parsing, so that "ip -o link" works again
      • +
    • other fixes and code size reductions in many applets
      • +
    +

    + The email address gpl@busybox.net is the recommended way to contact + the Software Freedom Law Center to report BusyBox license violations. +

    +
    • + +
  • 12 June 2008 -- Sponsors! +

    We want to thank the following companies which are providing support + for the BusyBox project: +

    + +
    • + +
  • 5 June 2008 -- BusyBox 1.10.3 (stable) +

    BusyBox 1.10.3. + (svn, + patches, + how to add a patch)

    +

    + Bugfix-only release for 1.10.x branch. It contains fixes for dnsd, fuser, hush, + ip, mdev and syslogd. +

    +
    • + +
  • 8 May 2008 -- BusyBox 1.10.2 (stable) +

    BusyBox 1.10.2. + (svn, + patches, + how to add a patch)

    +

    + 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. +

    Please note that mdev was backported from current svn trunk. Please + report if you encounter any problems with it. +

    +
    • + +
  • 19 April 2008 -- BusyBox 1.10.1 (stable) +

    BusyBox 1.10.1. + (svn, + patches, + how to add a patch)

    +

    + Bugfix-only release for 1.10.x branch. It contains fixes for + fuser, init, less, nameif, tail, taskset, tcpudp, top, udhcp. +

    • + +
  • 21 March 2008 -- BusyBox 1.10.0 (unstable) +

    BusyBox 1.10.0. + (svn, + patches, + how to add a patch)

    + +

    Sizes of busybox-1.9.2 and busybox-1.10.0 (with almost full config, static uclibc build):

    +   text    data     bss     dec     hex filename
+ 781405     679    7500  789584   c0c50 busybox-1.9.2
+ 773551     640    7372  781563   becfb busybox-1.10.0
+
    +

    Top 10 stack users:

    +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
+
    + +

    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. +

    +

    Made NOMMU-compatible: crond, crontab, ifupdown, inetd, init, runsv, svlogd, tcpsvd, udpsvd. +

    +

    Changes since previous release: +

    +
      +
    • globally: add -Wunused-parameter
      • +
    • globally: add optimization barrier to all "G trick" locations
      • +
    • adduser/addgroup: check username for invalid chars (by Tito <farmatito AT tiscali.it>)
      • +
    • adduser: optional support for long options. Closes bug 2134
      • +
    • ash: handle "A=1 A=2 B=$A; echo $B". Closes bug 947
      • +
    • ash: make ash -c "if set -o barfoo 2>/dev/null; then echo foo; else echo bar; fi" work. Closes bug 1142
      • +
    • build system: don't use "gcc -o /dev/null", old gcc can delete /dev/null in this case
      • +
    • build system: fixes for cross-compiling on an OS X host
      • +
    • build system: make it do without "od -t"
      • +
    • build system: pass CFLAGS to link stage too. Closes bug 1376
      • +
    • build system: add CONFIG_NOMMU
      • +
    • cp: add ENABLE_FEATURE_VERBOSE_CP_MESSAGE. Closes bug 1470
      • +
    • crontab: almost complete rewrite
      • +
    • dnsd: properly set _src_ IP:port on outgoing UDP packets
      • +
    • dpkg: fix bug where existence check was reversed
      • +
    • eject: add -s for SCSI- and USB-devices (Nico Erfurth)
      • +
    • fdisk: fix a case where break was reached only for DOS labels
      • +
    • fsck: don't kill pid -1! (Roy Marples <roy at marples.name>)
      • +
    • fsck_minix: fix bug in map_block2: s/(blknr >= 256 * 256)/(blknr < 256 * 256)/
      • +
    • fuser: substantial rewrite
      • +
    • getopt: add support for "a+" specifier for nonnegative int parameters. By Vladimir Dronnikov <dronnikov at gmail.com>
      • +
    • getty: don't try to detect parity on local lines (Joakim Tjernlund <Joakim.Tjernlund at transmode.se>)
      • +
    • halt: write wtmp entry if wtmp support is enabled
      • +
    • httpd: "HEAD" support. Closes bug 1530
      • +
    • httpd: fix bug 2004: wrong argv when interpreter is invoked
      • +
    • httpd: fix bug where we did chdir("") if CGI path had only one "/"
      • +
    • httpd: fix for POST upload
      • +
    • httpd: support for "I:index.xml" syntax (Peter Korsgaard <jacmet AT uclibc.org>)
      • +
    • hush: fix a case where none of pipe members could be started because of fork failure
      • +
    • hush: more correct handling of piping
      • +
    • hush: reinstate `cmd` handling for NOMMU
      • +
    • hush: report [v]fork failures
      • +
    • hush: set CLOEXEC on script file being executed
      • +
    • hush: try to add a bit more of vfork-friendliness
      • +
    • inetd: make "udp nowait" work
      • +
    • inetd: make inetd IPv6-capable
      • +
    • init: add FEATURE_KILL_REMOVED (Eugene Bordenkircher <eugebo AT gmail.com>)
      • +
    • init: allow last line of config file to be not terminated by "\n"
      • +
    • init: do not die if "/dev/null" is missing
      • +
    • init: fix bug 1111: restart actions were not splitting words
      • +
    • init: wait for orphaned children too while waiting for sysinit-like processes (harald-tuxbox AT arcor.de)
      • +
    • ip route: "ip route" was misbehaving (extra argv+1 ate 1st env var)
      • +
    • last: do not go into endless loop on read error
      • +
    • less,klogd,syslogd,nc,tcpudp: exit on signal by killing itself, not exit(1)
      • +
    • less: "examine" command will not bomb out on bad file name now
      • +
    • less: fix bug where backspace wasn't actually deleting chars
      • +
    • less: make it a bit more resistant against status line corruption
      • +
    • 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
      • +
    • 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!
      • +
    • libbb: filename completion matches dangling symlinks too
      • +
    • libbb: fix getopt state corruption for NOFORK applets
      • +
    • libbb: full_read/write now will report partial data counts prior to error
      • +
    • libbb: intrduce and use safe_gethostname. By Tito <farmatito AT tiscali.it>
      • +
    • libbb: introduce and use nonblock_safe_read(). Yay! Our shells are immune from this nasty O_NONBLOCK now!
      • +
    • login,su: avoid clearing environment with some options, as was intended
      • +
    • microcom: read more than 1 byte from device, if possible
      • +
    • microcom: split -d (delay) option away from -t
      • +
    • mktemp: support -p DIR (Timo Teras <timo.teras at iki.fi>)
      • +
    • mount: #ifdef out MOUNT_LABEL code parts if it is not selected
      • +
    • mount: add another mount helper call method
      • +
    • mount: allow and ignore _netdev option
      • +
    • mount: make -f work even without mtab support (Cristian Ionescu-Idbohrn <cristian.ionescu-idbohrn at axis.com>)
      • +
    • mount: optional support for -vv verbosity
      • +
    • mount: plug a hole where FEATURE_MOUNT_HELPERS could allow execution of arbitrary command
      • +
    • mount: recognize "dirsync" (closes bug 835)
      • +
    • mount: sanitize environment if called by non-root
      • +
    • mount: support for mount by label. Closes bug 1143
      • +
    • mount: with -vv -f, say what mount() calls we were going to make
      • +
    • msh: create testsuite (based on hush one)
      • +
    • msh: don't use floating point in "times" builtin
      • +
    • msh: fix Ctrl-C handling with line editing
      • +
    • msh: fix for bug 846 ("break" didn't work second time)
      • +
    • msh: glob0/glob1/glob2/glob3 were just a sorting routine, removed
      • +
    • msh: instead of fixing "ls | cd", "cd | ls" etc disallow builtins in pipes. They make no sense there anyway
      • +
    • msh: stop trying to parse variables in "msh SCRIPT VAR=val param". They are passed as ordinary parameters
      • +
    • netstat: print control chars as "^C" etc
      • +
    • nmeter: fix bug where %[mf] behaves as %[mt]
      • +
    • nohup: compat patch by Christoph Gysin <mailinglist.cache at gmail.com>
      • +
    • od: handle /proc files (which have filesize 0) correctly
      • +
    • patch: don't trash permissions of patched file
      • +
    • ps: add conditional support for -o [e]time
      • +
    • ps: fix COMMAND column adjustment; overflow in USER and VSZ columns
      • +
    • reset: call "stty sane". Closes bug 1414
      • +
    • rmdir: optional long options support for Debian users. By Roberto Gordo Saez <roberto.gordo AT gmail.com>
      • +
    • run-parts: add --reverse
      • +
    • script: correctly handle buffered "tail" of output
      • +
    • sed: "n" command must reset "we had successful subst" flag. Closes bug 1214
      • +
    • sort: -z outputs NUL terminated lines. Closes bug 1591
      • +
    • stty: fix mishandling of control keywords (Ralf Friedl <Ralf.Friedl AT online.de>)
      • +
    • switch_root: stop at first non-option. Closes bug 1425
      • +
    • syslogd: avoid excessive time() system calls
      • +
    • syslogd: don't die if remote host's IP cannot be resolved. Retry resolutions every two minutes instead
      • +
    • syslogd: fix shmat error check
      • +
    • syslogd: optional support for dropping dups. Closes bug 436
      • +
    • syslogd: send "\n"-terminated messages over the network. Fully closes bug 1574
      • +
    • syslogd: tighten up hostname handling
      • +
    • tail: fix "tail -c 20 /dev/huge_disk" (was taking ages)
      • +
    • tar: compat: handle tarballs with only one zero block at the end
      • +
    • tar: autodetection of gz/bz2 compressed tarballs. Closes bug 992
      • +
    • tar: real support for -p. By Natanael Copa <natanael.copa at gmail.com>
      • +
    • tcpudp: narrow down time window where we have no wildcard socket
      • +
    • telnetd: use login always, not "sometimes login, sometimes shell"
      • +
    • test: fix mishandling of "test ! arg1 op arg2 more args"
      • +
    • trylink: instead of build error, disable --gc-sections if GLIBC and STATIC are selected
      • +
    • udhcp: make file paths configurable
      • +
    • udhcp: optional support for non-standard DHCP ports
      • +
    • udhcp: set correct op byte in the packet for DHCPDECLINE
      • +
    • udhcpc: filter unwanted packets in kernel (Cristian Ionescu-Idbohrn <cristian.ionescu-idbohrn AT axis.com>)
      • +
    • udhcpc: fix wrong options in decline and release packets (Jonas Danielsson <jonas.danielsson AT axis.com>)
      • +
    • umount: do not complain several times about the same mountpoint
      • +
    • umount: do not try to free loop device or erase mtab if remounted ro
      • +
    • umount: instead of non-standard -D, use -d with opposite meaning. Closes bug 1604
      • +
    • unlzma: shrink by Pascal Bellard <pascal.bellard AT ads-lu.com>
      • +
    • unzip: do not try to read entire compressed stream at once (it can be huge)
      • +
    • unzip: handle short reads correctly
      • +
    • vi: many fixes
      • +
    • zcip: don't chdir to root
      • +
    • zcip: open ARP socket before openlog (else we can trash syslog socket)
      • +
    +
    • + +
  • 21 March 2008 -- BusyBox old stable releases +

    + Bugfix-only releases for four past branches. Links to locations + for future hot patches are in parentheses. +

    + 1.9.2 + (patches), + 1.8.3 + (patches), + 1.7.5 + (patches), + 1.5.2 + (patches). +

    + How to add a patch. +

    + + +
  • 12 February 2008 -- BusyBox 1.9.1 (stable) +

    BusyBox 1.9.1. + (svn, + patches, + how to add a patch)

    + +

    This is a bugfix-only release, with fixes to fsck, + iproute, mdev, mkswap, msh, nameif, stty, test, zcip.

    +

    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.

    +
    • + +
  • 24 December 2007 -- BusyBox 1.9.0 (unstable) +

    BusyBox 1.9.0. + (svn, + patches, + how to add a patch)

    + +

    Sizes of busybox-1.8.2 and busybox-1.9.0 (with almost full config, static uclibc build):

    +   text    data     bss     dec     hex filename
+ 792796     978    9724  803498   c42aa busybox-1.8.2
+ 783803     683    7508  791994   c15ba busybox-1.9.0
+
    +

    Top 10 stack users:

    +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
+
    + +

    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. + +

    init has some changes in this release, please report if it causes + problems for you. + +

    Changes since previous release: +

      +
    • Build system improvements +
    • Testsuite additions +
    • Stack size reductions, code size reductions, data/bss reductions +
    • An option to prefer IPv4 address if host has both +
    • New applets: hd, sestatus +
    • Removed applets: lash +
    • hush: fixed a few bugs, wired up echo and test to be builtins +
    • init: simplify forking of children +
    • getty: special handling of '#' and '@' is removed +
    • [su]login: sanitize environment if called by non-root +
    • udhcpc: support "bad" servers which send oversized packets + (Cristian Ionescu-Idbohrn <cristian.ionescu-idbohrn at axis.com>) +
    • udhcpc: -O option allows to specify which options to ask for + (Stefan Hellermann <stefan at the2masters.de>) +
    • udhcpc: optionally check whether given IP is really free (by ARP ping) + (Jonas Danielsson <jonas.danielsson at axis.com>) +
    • vi: now handles files with unlimited line length +
    • vi: speedup for huge line lengths +
    • vi: Del key works +
    • sed: support GNUism '\t' +
    • cp/mv/install: optionally use bigger buffer for bulk copying +
    • line editing: don't eat stack like crazy +
    • passwd: follows symlinked /etc/passwd +
    • renice: accepts priority with +N too +
    • netstat: wide output mode +
    • nameif: extended matching (Nico Erfurth <masta at perlgolf.de>) +
    • test: become NOFORK applet +
    • find: -iname (Alexander Griesser <alexander.griesser at lkh-vil.or.at>) +
    • df: -i option (show inode info) (Pascal Bellard <pascal.bellard at ads-lu.com>) +
    • hexdump: -R option (Pascal Bellard <pascal.bellard at ads-lu.com>) +
    +
    • + +
  • 23 November 2007 -- BusyBox 1.8.2 (stable), BusyBox 1.7.4 (stable) +

    BusyBox 1.8.2. + (svn, + patches, + how to add a patch)

    +

    BusyBox 1.7.4. + (svn, + patches, + how to add a patch)

    + +

    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.

    +
    • + +
  • 9 November 2007 -- BusyBox 1.8.1 (stable) +

    BusyBox 1.8.1. + (svn, + patches, + how to add a patch)

    + +

    This is a bugfix-only release, with fixes to login (PAM), modprobe, syslogd, telnetd, unzip.

    +
    • + +
  • 4 November 2007 -- BusyBox 1.8.0 (unstable) +

    BusyBox 1.8.0. + (svn, + patches, + how to add a patch)

    + +

    Note: this is probably the very last release with lash. It will be dropped. Please migrate to hush. + +

    Applets which had many changes since 1.7.x: +

    httpd: +

      +
    • does not clear environment, CGIs will see all environment variables which were set for httpd +
    • fix bug where we were trying to read more POSTDATA than content-length +
    • fix trivial bug (spotted by Alex Landau) +
    • optional support for partial downloads +
    • simplified CGI i/o loop (now it looks good to me) +
    • small auth and IPv6 fixes (Kim B. Heino <Kim.Heino at bluegiga.com>) +
    • support for proxying connection to other http server (by Alex Landau <landau_alex at yahoo.com>) +
    + +

    top: +

      +
    • TOPMEM feature - 's(how sizes)' command +
    • don't wait before final bailout (try top -b -n1) +
    • fix for command line wrapping +
    + +

    Build system improvements: libbusybox mode restored (it was lost in transition to new makefiles). + +

    Code and data size in comparison with 1.7.3:

    +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
    + +

    New applets: +

      +
    • microcom: new applet by Vladimir Dronnikov <dronnikov at gmail.ru> +
    • kbd_mode: new applet by Loic Grenie <loic.grenie at gmail.com> +
    • bzip2: port bzip2 1.0.4 to busybox, 9 kb of code +
    • pgrep, pkill: new applets by Loic Grenie <loic.grenie at gmail.com> +
    • setsebool: new applet (Yuichi Nakamura <ynakam at hitachisoft.jp>) +
    + +

    Other changes since previous release (abridged): +

      +
    • cp: -r and -R imply -d (coreutils compat) +
    • cp: detect and prevent infinite recursion +
    • cp: make it a bit closer to POSIX, but still refuse to open and overwrite symbolic link +
    • hdparm: reduce possibility of numeric overflow in -T +
    • hdparm: simplify timing measurement +
    • wget: -O FILE is allowed to overwrite existing file (compat) +
    • wget: allow dots in header field names +
    • telnetd: add -K option to close sessions as soon as child exits +
    • telnetd: don't SIGKILL child when closing the session, kernel will send SIGHUP for us +
    • ed: large cleanup, add line editing +
    • hush: feeble attempt at making it more NOMMU-friendly +
    • hush: fix glob() +
    • hush: stop doing manual accounting of open fd's, kernel can do it for us +
    • adduser: implement -S and fix uid selection +
    • ash: fix prompt expansion (Natanael Copa <natanael.copa at gmail.com>) +
    • ash: revert "cat | jobs" fix, it causes more problems than good +
    • find: fix -xdev behavior in the presence of two or more nested mount points +
    • grep: fix grep -F -e str1 -e str2 (was matching str2 only) +
    • grep: optimization: stop on first -e match +
    • gunzip: support concatenated gz files +
    • inetd: fix bug 1562 "inetd does not set argv[0] properly" (fix by Ilya Panfilov) +
    • install: 'support' (by ignoring) -v and -b +
    • install: fix bug in "install -c file dir" (tried to copy dir into dir too) +
    • ip: tunnel parameter parsing fix by Jean Wolter <jw5 at os.inf.tu-dresden.de> +
    • isrv: use monotonic_sec +
    • less: make 'f' key page forward +
    • libiproute: add missing break statements +
    • load_policy: update (Yuichi Nakamura <ynakam at hitachisoft.jp>) +
    • logger: fix a problem of losing all argv except first +
    • login: do reject wrong passwords with PAM auth +
    • losetup: support -f (Loic Grenie <loic.grenie at gmail.com>) +
    • fdisk: make fdisk compile on libc without llseek64 +
    • libbb: by popular request allow PATH to be customized at build time +
    • mkswap: selinux support by KaiGai Kohei <kaigai at ak.jp.nec.com> +
    • mount: allow (and ignore) -i +
    • mount: ignore NFS bg option on NOMMU machines +
    • mount: mount helpers support (by Vladimir Dronnikov <dronnikov at gmail.ru>) +
    • passwd: handle Ctrl-C, restore termios on Ctrl-C +
    • passwd: SELinux support by KaiGai Kohei <kaigai at ak.jp.nec.com> +
    • ping: make -I ethN work too (-I addr already worked) +
    • ps: fix RSS parsing (rss field in /proc/PID/stat is in pages, not bytes) +
    • read_line_input: fix it to not do any fancy editing if echoing is disabled +
    • run_parts: make it sort executables by name (required by API) +
    • runsv: do not use clock_gettime if !MONOTONIC_CLOCK +
    • runsvdir: fix "linear wait time" bug +
    • sulogin: remove alarm handling, it is redundant there +
    • svlogd: compat: svlogd -tt should timestamp stderr too +
    • syslogd: bail out if you see null read from Unix socket +
    • syslogd: do not need to poll(), we can just block in read() +
    • tail: work correctly on /proc files (Kazuo TAKADA <kztakada at sm.sony.co.jp>) +
    • tar + gzip/bzip2/etc: support NOMMU machines (by Alex Landau <landau_alex at yahoo.com>) +
    • tar: strip leading '/' BEFORE memorizing hardlink's name +
    • tftp: fix infinite retry bug +
    • umount: support (by ignoring) -i; style fixes +
    • unzip: fix endianness bugs +
    • vi: don't wait 50 ms before reading ESC sequences +
    • watchdog: allow millisecond spec (-t 250ms) +
    • zcip: fix unaligned trap on ARM +
    +
    • + +
  • 4 November 2007 -- BusyBox 1.7.3 (stable) +

    BusyBox 1.7.3. + (svn, + patches, + how to add a patch)

    + +

    This is a bugfix-only release, with fixes to ash, httpd, inetd, iptun, logger, login, tail.

    +
    • + +
  • 30 September 2007 -- BusyBox 1.7.2 (stable) +

    BusyBox 1.7.2. + (svn, + patches, + how to add a patch)

    + +

    This is a bugfix-only release, with fixes to install, find, login, httpd, runsvdir, chcon, setfiles, fdisk and line editing.

    +
    • + +
  • 16 September 2007 -- BusyBox 1.7.1 (stable) +

    BusyBox 1.7.1. + (svn, + patches, + how to add a patch)

    + +

    This is a bugfix-only release, with fixes to cp, runsv, tar, busybox --install and build system.

    +
    • + +
  • 24 August 2007 -- BusyBox 1.7.0 (unstable) +

    BusyBox 1.7.0. + (svn, + patches, + how to add a patch)

    + +

    Applets which had many changes since 1.6.x: +

    httpd: +

      +
    • works in standalone mode on NOMMU machines now (partly by Alex Landau <landau_alex at yahoo.com>) +
    • indexer example is rewritten in C +
    • optional support for error pages (by Pierre Metras <genepi at sympatico.ca>) +
    • stop reading headers using 1-byte reads +
    • new option -v[v]: prints client addresses, HTTP codes returned, URLs +
    • extended -p PORT to -p [IP[v6]:]PORT +
    • sendfile support (by Pierre Metras <genepi at sympatico.ca>) +
    • add support for Status: CGI header +
    • fix CGI handling bug (we were closing wrong fd) +
    • CGI I/O loop still doesn't look 100% ok to me... +
    + +

    udhcp[cd]: +

      +
    • add -f "foreground" and -S "syslog" options +
    • fixed "ifupdown + udhcpc_without_pidfile_creation" bug +
    • new config option "Rewrite the lease file at every new acknowledge" (Mats Erik Andersson <mats at blue2net.com> (Blue2Net AB)) +
    • consistently treat server_config.start/end IPs as host-order +
    • fix IP parsing for 64bit machines +
    • fix unsafe hton macro usage in read_opt() +
    • do not chdir to / when daemonizing +
    + +

    top, ps, killall, pidof: +

      +
    • simpler loadavg processing +
    • truncate usernames to 8 chars +
    • fix non-CONFIG_DESKTOP ps -ww (by rockeychu) +
    • improve /proc/PID/cmdinfo reading code +
    • 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) +
    • reduce CPU usage in decimal conversion (optional) (corresponding speedup on kernel side is accepted in mainline Linux kernel, yay!) +
    • make percentile (0.1%) calculations configurable +
    • add config option and code for global CPU% display +
    • reorder columns, so that [P]PIDs are together and VSZ/%MEM are together - makes more sense +
    + +

    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). + +

    Code and data size in comparison with 1.6.1:

    +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
    + +

    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. + +

    New applets: +

      +
    • pscan, expand, unexpand (from Tito <farmatito at tiscali.it>) +
    • setfiles, restorecon (by Yuichi Nakamura <ynakam at hitachisoft.jp>) +
    • chpasswd (by Alexander Shishkin <virtuoso at slind.org>) +
    • slattach, ttysize +
    + +

    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. + +

    Other changes since previous release (abridged): +

      +
    • addgroup: disallow addgroup -g num user group; make -g 0 work (Tito <farmatito at tiscali.it>) +
    • adduser: close /etc/{passwd,shadow} before calling passwd etc. Spotted by Natanael Copa <natanael.copa at gmail.com> +
    • arping: -i should be -I, fixed +
    • ash: make "jobs | cat" work like in bash (was giving empty output) +
    • ash: recognize -l as --login equivalent; do not recognize +-login +
    • ash: fix buglet in DEBUG code (Nguyen Thai Ngoc Duy <pclouds at gmail.com>) +
    • ash: fix SEGV if type has zero parameters +
    • awk: fix -F 'regex' bug (miscounted fields if last field is empty) +
    • catv: catv without arguments was trying to use environ as argv (Alex Landau <landau_alex at yahoo.com>) +
    • catv: don't die on open error (emit warning) +
    • chown/chgrp: completely match coreutils 6.8 wrt symlink handling +
    • correct_password: do not print "no shadow passwd..." message +
    • crond: don't start sendmail with absolute path, don't report obsolete version (report true bbox version) +
    • dd: fix bug where we assume count=INT_MAX when count is unspecified +
    • devfsd: sanitization by Tito <farmatito at tiscali.it> +
    • echo: fix non-fancy echo +
    • fdisk: make it work with big disks (read: typical today's disks) even if CONFIG_LFS is unset +
    • find: -context support for SELinux (KaiGai Kohei <kaigai at kaigai.gr.jp>) +
    • find: add conditional support for -maxdepth and -regex, make -size match GNU find +
    • find: fix build failure on certain configs (found by Cristian Ionescu-Idbohrn <cristian.ionescu-idbohrn at axis.com>) +
    • fsck_minix: make it print bb version, not it's own (outdated/irrelevant) one +
    • grep: implement -m MAX_MATCHES, fix buglets with context printing +
    • grep: fix selection done by FEATURE_GREP_EGREP_ALIAS (Maxime Bizon <mbizon at freebox.fr> (Freebox)) +
    • hush: add missing dependencies (Maxime Bizon <mbizon at freebox.fr> (Freebox)) +
    • hush: fix read builtin to not read ahead past EOL and to not use insane amounts of stack +
    • ifconfig: make it work with ifaces with interface no. > 255 +
    • ifup/ifdown: make location of ifstate configurable +
    • ifupdown: make netmask parsing smaller and more strict (was accepting 255.0.255.0, 255.1234.0.0 etc...) +
    • install: fix -s (strip) option, fix install a b /a/link/to/dir +
    • libbb: consolidate ARRAY_SIZE macro (Walter Harms <wharms at bfs.de>) +
    • libbb: make /etc/network parsing configurable. -200 bytes when off +
    • libbb: nuke BB_GETOPT_ERROR, always die if there are mutually exclusive options +
    • libbb: xioctl and friends by Tito <farmatito at tiscali.it> +
    • login: optional support for PAM +
    • login: make /etc/nologin support configurable (-240 bytes) +
    • login: ask passwords even for wrong usernames +
    • md5_sha1_sum: fix mishandling when run as /bin/md5sum +
    • mdev: add support for firmware loading +
    • mdev: work even when CONFIG_SYSFS_DEPRECATED in kernel is off +
    • modprobe: add scanning of /lib/modules/`uname -r`/modules.symbols (by Yann E. MORIN <yann.morin.1998 at anciens.enib.fr>) +
    • more: fixes by Tristan Schmelcher <tpkschme at engmail.uwaterloo.ca> +
    • nc: make connecting to IPv4 from IPv6-enabled hosts easier (was requiring -s local_addr) +
    • passwd: fix bug "updating shadow even if user's record is in passwd" +
    • patch: fix -p -1 handling +
    • patch: fix bad line ending handling (Nguyen Thai Ngoc Duy <pclouds at gmail.com>) +
    • ping: display roundtrip times with 1/1000th of ms, not 1/10 ms precision. +
    • ping: fix incorrect handling of -I (Iouri Kharon <bc-info at styx.cabel.net>) +
    • ping: fix non-fancy ping6 +
    • printenv: fix "printenv VAR1 VAR2" bug (spotted by Kalyanatejaswi Balabhadrapatruni <kalyanatejaswi at yahoo.co.in>) +
    • ps: fix -Z (by Yuichi Nakamura <ynakam at hitachisoft.jp>) +
    • rpm: add optional support for bz2 data. +50 bytes of code +
    • rpm: fix bogus "package is not installed" case +
    • sed: fix 'q' command handling (by Nguyen Thai Ngoc Duy <pclouds at gmail.com>) +
    • start_stop_daemon: NOMMU fixes by Alex Landau <landau_alex at yahoo.com> +
    • stat: fix option -Z SEGV +
    • strings: strings a b was processing a twice, fix that +
    • svlogd: fix timestamping, do not warn if config is missing +
    • syslogd, logread: get rid of head pointer, fix logread bug in the process +
    • syslogd: do not convert tabs to ^I, set syslog IPC buffer to mode 0644 +
    • tar: improve OLDGNU compat, make old SUN compat configurable +
    • test: fix testing primary expressions like '"-u" = "-u"' +
    • uudecode: fix to base64 decode by Jorgen Cederlof <jcz at google.com> +
    • vi: multiple fixes by Natanael Copa <natanael.copa at gmail.com> +
    • wget: fix bug in base64 encoding (bug 1404). +10 bytes +
    • wget: lift 256 chars limitation on terminal width +
    • wget, zcip: use monotonic_sec instead of gettimeofday +
    +
    • + +
  • 30 June 2007 -- BusyBox 1.6.1 (stable) +

    BusyBox 1.6.1. + (svn, + patches, + how to add a patch)

    + +

    This is a bugfix-only release, with fixes to echo, hush, and wget.

    +
    • + +
  • 1 June 2007 -- BusyBox 1.6.0 (unstable) +

    BusyBox 1.6.0. + (svn, + patches, + how to add a patch)

    + +

    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.

    +

    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.

    +

    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.

    +

    Memory usage has decreased, but we can do better still

    +

    Other changes since previous release: +

      +
    • NOFORK: audit small applets and mark some of them as NOFORK. Put big scary warnings in relevant places +
    • NOFORK: factor out NOFORK/NOEXEC code from find. Use NOFORK/NOEXEC in find and xargs +
    • NOFORK: remove potential xmalloc from NOFORK path in bb_full_fd_action +
    • NOMMU: random fixes; compressed --help now works for NOMMU +
    • SELinux: load_policy applet +
    • [u]mount: extend -t option (Roy Marples <uberlord at gentoo.org>) +
    • addgroup: clean up, fix adding users to existing groups and make it optional (Tito) +
    • adduser: don't bomb out if shadow password file doesn't exist (from Tito <farmatito at tiscali.it>) +
    • applet.c: do not even try to read config if run by real root; fix suid config handling +
    • ash: fix infinite loop on exit if tty is not there anymore +
    • ash: fix kill -l (by Mats Erik Andersson <mats.andersson64 at comhem.se>) +
    • ash: implement type -p, costs less than 10 bytes (patch by Mats Erik Andersson <mats.andersson64 at comhem.se>) +
    • awk: don't segfault on printf(%*s). Closes bug 1337 +
    • awk: guard against empty environment +
    • awk: some 'lineno' vars were shorts, made them ints (code got smaller) +
    • cat: stop using stdio.h opens +
    • config system: clarify PREFER_APPLETS/SH_STANDALONE effects in help text +
    • cryptpw: new applet (by Thomas Lundquist <lists at zelow.no>) +
    • cttyhack: new applet +
    • dd: NOEXEC fix; fix skip= parse error (spotted by Dirk Clemens <develop at cle-mens.de>) +
    • deluser: add optional support for removing users from groups (by Tito <farmatito at tiscali.it>) +
    • diff: fix SEGV (NULL deref) in diff -N +
    • diff: fix segfault on empty dirs (Peter Korsgaard <peter.korsgaard at barco.com>) +
    • dnsd: fix several buglets, make smaller; openlog(), so that applet's name is logged +
    • 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>) +
    • dpkg: use bitfields which are a bit closer to typical short/char. Code size -800 bytes +
    • dumpleases: getopt32()-ization (from Mats Erik Andersson <mats.andersson64 at comhem.se>) +
    • e2fsprogs: stop using statics in chattr. Minor code shrinkage (-130 bytes) +
    • ether-wake: close bug 1317. Reorder fuctions to avoid forward refs while at it +
    • ether-wake: save a few more bytes of code +
    • find: -group, -depth (Natanael Copa <natanael.copa at gmail.com>) +
    • find: add support for -delete, -path (by Natanael Copa) +
    • find: fix -prune. Add big comment about it +
    • find: improve usage text (Natanael Copa <natanael.copa at gmail.com>) +
    • find: missed 'static' on const data; size and prune were mixed up; use index_in_str_array +
    • find: un-DESKTOPize (Kai Schwenzfeier <niteblade at gmx.net>) +
    • find_root_device: teach to deal with /dev/ subdirs (by Kirill K. Smirnov <lich at math.spbu.ru>) +
    • find_root_device: use lstat - don't follow links +
    • getopt32: fix llist_t options ordering. llist_rev is now unused +
    • getopt: use getopt32 for option parsing - inspired by patch by Mats Erik Andersson <mats.andersson64 at comhem.se> +
    • hdparm: fix multisector mode setting (from Toni Mirabete <amirabete at catix.cat>) +
    • hdparm: make -T -t code smaller (-194 bytes), and output prettier +
    • ifupdown: make it possible to use DHCP clients different from udhcp +
    • ifupdown: reread state file before rewriting it. Fixes "ifup started another ifup" state corruption bug. Patch by Natanael Copa <natanael.copa at gmail.com> +
    • ifupdown: small optimization (avoid doing useless work if we are not going to update state file) +
    • ip: fix compilation if FEATURE_TR_CLASSES is off +
    • ip: mv ip*_main into ip.c; use a dispatcher to save on needless duplication. Saves a minor 12b +
    • ip: rewrite the ip applet to be less bloaty. Convert to index_in_(sub)str_array() +
    • ip: set the scope properly. Thanks to Jean Wolter +
    • iplink: shrink iplink; sanitize libiproute a bit (-916 bytes) +
    • iproute: shrink a bit (-200 bytes) +
    • kill: know much more signals; make code smaller; use common code for kill applet and ash kill builtin +
    • klogd: remove dependency on syslogd +
    • 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. +
    • lash: fix kill buglet (didn't properly recognize ESRCH) +
    • lash: make -c work; crush buffer overrun and free of non-malloced ptr (from Mats Erik Andersson <mats.andersson64 at comhem.se>) +
    • lash: recognize and use NOFORK applets +
    • less: fix case when regex search finds nothing; fix very obscure memory corruption bug; fix less <HUGEFILE + [End] busy loop +
    • libbb: add xsendto, xunlink, xpipe +
    • libbb: fix segfault in reset_ino_dev_hashtable() when *hashtable was NULL +
    • libbb: make pidfile writing configurable +
    • libbb: make xsocket die with address family printed (if VERBOSE_RESOLUTION_ERRORS=y) +
    • libbb: rework NOMMU helper API so that it makes more sense and easier to use +
    • libiproute: audit callgraph, shortcut error paths into die() functions +
    • lineedit: do not try to open NULL history file +
    • lineedit: nuke two unused variables and code which sets them +
    • login: remove setpgrp call (makes it work from shell prompt again); sanitize stdio descriptors (we are suid, need to be careful!) +
    • login: shrink login and set_environment by ~100 bytes +
    • mount: fix incorrect usage of strtok (inadvertently used NULL sometimes) +
    • mount: fix mounting of symlinks (mount from util-linux allows that) +
    • 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 +
    • nc: port nc 1.10 to busybox +
    • netstat: fix for bogus state value for raw sockets +
    • netstat: introduce -W: wide, ipv6-friendly output; shrink by ~500 bytes +
    • nmeter: should die if stdout doesn't like him anymore +
    • patch: do not try to delete same file twice +
    • ping: fix wrong sign extension of packet id (bug 1373) +
    • ps: add -o tty and -o rss support; make a bit smaller; work around libc bug: printf("%.*s\n", MAX_INT, buffer) +
    • run_parts: rewrite +
    • 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> +
    • sed: fix escaped newlines in -f +
    • split: new applet +
    • stat: remove superfluous bss user (flags) and manually unswitch some areas +
    • stty: fix option parsing bug (spotted by Sascha Hauer <s.hauer at pengutronix.de>) +
    • svlogd: fix 'SEGV on uninitialized data' and make it honor TERM +
    • tail: fix SEGV on "tail -N" +
    • 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/ +
    • test: close bug 1371; plug a memory leak; code size reduction +
    • tftp: code diet, and I think retransmits were broken +
    • tr: fix bug where we did not reject invalid classes like '[[:alpha'. debloat while at it +
    • udhcp: MAC_BCAST_ADDR and blank_chaddr are in fact constant, move to rodata; use pipe instead of socketpair +
    • udhcp[cd]: stop using atexit magic fir pidfile removal; stop deleting our own pidfile if we daemonize +
    • xargs: shrink code, ~80 bytes; simplify word list management +
    • zcip: make it work on NOMMU (+ improve NOMMU support machinery) +
    +
    • + +
  • 20 May 2007 -- BusyBox 1.5.1 (stable) +

    BusyBox 1.5.1. + (patches, + how to add a patch)

    + +

    This is a bugfix-only release, with fixes to hdparm, hush, ifupdown, ps + and sed.

    +
    • + +
  • 23 March 2007 -- BusyBox 1.5.0 (unstable) +

    BusyBox 1.5.0. + (patches, + how to add a patch)

    + +

    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.

    +

    Notable changes since previous release: +

      +
    • find: added support for -user, -not, fixed -mtime, -mmin, -perm +
    • [de]archivers: merge common logic into one module +
    • ping[6]: unified code for both +
    • less: regex search improved +
    • ash: more readable code, testsuite added +
    • sed: several very obscure bugs fixed +
    • chown: -H, -L, -P support (required by POSIX) +
    • tar: handle (broken) checksums a-la Sun; tar restores mode again +
    • grep: implement -w, "implement" -a and -I by ignoring them +
    • cp: more sane behavior when overwriting existing files +
    • init: stop doing silly things with the console (-400 bytes) +
    • httpd: make httpd usable for NOMMU CPUs; fix POSTDATA handling bugs +
    • httpd: run interpreter for configured file extensions in any dir, + not only in /cgi-bin/ +
    • chrt: new applet +
    • SELinux: SELinux-related code and -Z option added to several applets, + new SELinux-specific applets: chcon, runcon. +
    • Build system: produces link map, uses -Wwrite-strings to catch + improper usage of string constants. +
    • Data and bss section usage audited and reduced - should help NOMMU + targets. +
    • Applets with bug fixes: gunzip, vi, syslogd, dpkg, ls, adjtimex, resize, + sv, printf, diff, awk, sort, dpkg, diff, tftp +
    • Applets with usability improvements: swapon, more, ifup/ifdown, hwclock, + udhcpd, start_stop_daemon, cmp +
    • Applets with code cleaned up: telnet, fdisk, fsck_minix, mkfs_minix, + syslogd, swapon, runsv, svlogd, klogd +
    +
    • + +
  • 18 March 2007 -- BusyBox 1.4.2 (stable) +

    BusyBox 1.4.2. +

    + +

    This release includes only trivial fixes accumulated since 1.4.1. +

    +
    • + +
  • 25 January 2007 -- BusyBox 1.4.1 (stable) +

    BusyBox 1.4.1. + (patches)

    + +

    This release includes only trivial fixes accumulated since 1.4.0. +

    +
    • + +
  • 20 January 2007 -- BusyBox 1.4.0 (stable) +

    BusyBox 1.4.0. + (patches)

    + +

    Since this is a x.x.0 release, it probably is a bit less "stable" + than usual.

    +

    Changes since previous release: +

      +
    • 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. +
    • 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. +
    • 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. +
    • arp: new applet (thanks to Eric Spakman). +
    • fakeidentd: non-forking standalone server part was taking ~90% + of the applet. Factored it out (in fact, rewrote it). +
    • syslogd: mostly rewritten. +
    • decompress_unzip, gzip: sanitized a bit. +
    • sed: better hadling of NULs +
    • httpd: stop adding our own "Content-type:" to CGI output +
    • chown: user.grp works again. +
    • minor bugfixes to: passwd, date, tftp, start_stop_daemon, tar, + ps, ifupdown, time, su, stty, awk, ping[6], sort,... +
    +
    • + +
  • 20 January 2007 -- BusyBox 1.3.2 (stable) +

    BusyBox 1.3.2.

    + +

    This release includes only one trivial fix accumulated since 1.3.1 +

    +
    • + +
  • 27 December 2006 -- BusyBox 1.3.1 (stable) +

    BusyBox 1.3.1. + (patches)

    + +

    Closing 2006 with new release. It includes only trivial fixes accumulated since 1.3.0 +

    +
    • + +
  • 14 December 2006 -- BusyBox 1.3.0 (stable) +

    BusyBox 1.3.0. + (patches)

    + +

    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. +

    Changes since previous release: +

      +
    • find: taking many more of standard options +
    • ps: POSIX-compliant -o implemented +
    • cp: added -s, -l +
    • grep: added -r, fixed -h +
    • watch: make it exec child like standard one does (was totally + incompatible) +
    • 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). +
    • httpd: added -i (inetd), -f (foreground), support for + directory indexer CGI (example is included), bugfixes. +
    • telnetd: fixed/improved IPv6 support, inetd+standalone support, + other fixes. Useful IPv6 stuff factored out into libbb. +
    • runit/*: new applets adapted from http://smarden.sunsite.dk/runit/ + (these are my personal favorite small-and-beautiful toys) +
    • minor bugfixes to: login, dd, mount, umount, chmod, chown, ln, udhcp, + fdisk, ifconfig, sort, tee, mkswap, wget, insmod. +
    +

    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. +

    +
    • + +
  • 29 October 2006 -- BusyBox 1.2.2.1 (fix) +

    BusyBox 1.2.2.1.

    + +

    Added compile-time warning that static linking against glibc + produces buggy executables. +

    • + +
  • 24 October 2006 -- BusyBox 1.2.2 (stable) +

    It's a bit overdue, but + here is + BusyBox 1.2.2.

    + +

    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.

    + +

    As Linux Weekly News noted, + this is my (Rob's) last release of BusyBox. The new maintainer is Denis + Vlasenko, I'm off to do other things. +

    +
    • + +
  • 29 September 2006 -- New license email address. +

    The email address gpl@busybox.net is now the recommended way to contact + the Software Freedom Law Center to report BusyBox license violations.

    + +
  • 31 July 2006 -- BusyBox 1.2.1 (stable) +

    Since nobody seems to have objected too loudly over the weekend, I + might as well point you all at + Busybox + 1.2.1, a bugfix-only release with no new features.

    + +

    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.

    + +

    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.

    + +
  • 30 June 2006 -- BusyBox 1.2.0 +

    The -devel branch has been stabilized and the result is + Busybox + 1.2.0. Lots of stuff changed, I need to work up a decent changelog + over the weekend.

    + +

    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. :)

    + +

    Update: Here are the first few bug fixes that will go into 1.2.1.

    + +
  • 17 May 2006 -- BusyBox 1.1.3 (stable) +

    BusyBox + 1.1.3 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.

    + +

    Expect 1.2.0 sometime next month, which won't be a bugfix release.

    + +
  • 10 April 2006 -- BusyBox 1.1.2 (stable) +

    You can now download BusyBox 1.1.2, 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.

    + +

    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.)

    + +
  • 27 March 2006 -- Software Freedom Law Center representing BusyBox and uClibc +

    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 + Hall of Shame), 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 + Groklaw for suggestions. She + referred us to the fine folks at softwarefreedom.org.

    + +

    As a result, we're pleased to announce that the + Software Freedom Law Center + has agreed to represent BusyBox and uClibc. We join a number of other + free and open source software projects (such as + X.org, + Wine, and + Plone + in being represented by a fairly cool bunch of lawyers, which is not a + phrase you get to use every day.

    + +
  • 22 March 2006 -- BusyBox 1.1.1 +

    The new maintainer is Rob Landley, and the new release is BusyBox 1.1.1. Expect a "what's new" document in a few days. (Also, Erik and I have have another announcement pending...)

    +

    Update: Rather than put out an endless stream of 1.1.1.x releases, + the various small fixes have been collected together into a + patch, + and new fixes will be appended to that as needed. Expect 1.1.2 around + June.

    +
    • +
  • 11 January 2006 -- 1.1.0 is out +

    The new stable release is + BusyBox + 1.1.0. It has a number of improvements, including several new applets. + (It also has a few rough spots, + but we're trying out a "release early, release often" strategy to see how + that works. Expect 1.1.1 sometime in March.)

    + +
  • 31 October 2005 -- 1.1.0-pre1 +

    The development branch of busybox is stable enough for wider testing, so + you can now + download, + the first prerelease of 1.1.0. This prerelease includes a lot of + new + functionality: new applets, new features, and extensive rewrites of + several existing applets. This prerelease should be noticeably more + standards + compliant than earlier versions of busybox, although we're + still working out the bugs.

    + +
  • 16 August 2005 -- 1.01 is out + +

    A new stable release (BusyBox + 1.01) is now available for download, containing over a hundred + small + fixes that have cropped up since the 1.00 release.

    + +
  • 13 January 2005 -- Bug and Patch Tracking

    + + 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 + shiny new Bug and Patch Tracking System + to post all the gory details. + +

    + + 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. + + +

    +

  • 13 October 2004 -- BusyBox 1.00 released

    + + 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. + +

    + + 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! + +

    + + 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. + +

    + + 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 BusyBox FAQ. + +

    + + As usual you can download busybox here. + +

    Have Fun! + +

    +

  • Old News

    + Click here to read older news + + +

  • 16 August 2004 -- BusyBox 1.0.0-rc3 released

    + + Here goes release candidate 3... +

    + The changelog has all the details. + And as usual you can download busybox here. + +

    Have Fun! + +

    +

  • 26 July 2004 -- BusyBox 1.0.0-rc2 released

    + + Here goes release candidate 2... +

    + The changelog has all the details. + And as usual you can download busybox here. + +

    Have Fun! + +

    +

  • 20 July 2004 -- BusyBox 1.0.0-rc1 released

    + + 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. +

    + + I really 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.... +

    + + 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! + +

    + The changelog has all the details. + And as usual you can download busybox here. + +

    Have Fun! + +

    + 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 OLS and give my presentation + as scheduled. +

    + 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. +

    + + +

    +

  • 13 April 2004 -- BusyBox 1.0.0-pre10 released

    + + 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 really + 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 very helpful if + people could continue to review the BusyBox documentation and submit + improvements. + +

    + The changelog has all the details. + And as usual you can download busybox here. + +

    Have Fun! +

    + + +

    +

  • 6 April 2004 -- BusyBox 1.0.0-pre9 released

    + + 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 + very 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. + +

    + I had hoped to get this released a month ago, but + + another release on 1 March 2004 has kept me busy... + +

    + The changelog has all the details. + And as usual you can download busybox here. + +

    Have Fun! +

    + + +

    +

  • 23 February 2004 -- BusyBox 1.0.0-pre8 released

    + + 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 very 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. + +

    + + The changelog has all the details. + And as usual you can download busybox here. + +

    Have Fun! +

    + + +

  • 4 February 2004 -- BusyBox 1.0.0-pre7 released

    + + 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. + +

    + + The changelog has all + the details. And as usual you can + download busybox here. + +

    Have Fun! +

    + + +

    +

  • 30 January 2004 -- BusyBox 1.0.0-pre6 released

    + + 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. + +

    + + People who rely on the daily BusyBox snapshots + 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. + +

    + + The changelog has all + the details. And as usual you can + download busybox here. + +

    Have Fun! +

    + + +

    +

  • 23 December 2003 -- BusyBox 1.0.0-pre5 released

    + + 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. + +

    + + If you see any problems, of have suggestions to make, as + always, please feel free to send an email to the busybox + mailing list. + +

    + + The changelog has all + the details. And as usual you can + download busybox here. + +

    Have Fun! +

    + + + +

  • 10 December 2003 -- BusyBox 1.0.0-pre4 released

    + + 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! + +

    + + 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. + +

    + + The changelog has all + the details. And as usual you can + download busybox here. + +

    Have Fun! + + + +

    +

  • 12 Sept 2003 -- BusyBox 1.0.0-pre3 released

    + + 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! + +

    + + 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! + +

    + + 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. + +

    + + 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 + uClibc + 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. + +

    + + The changelog has all + the details. And as usual you can + download busybox here. + +

    Have Fun! + + +

    +

  • 30 July 2003 -- BusyBox 1.0.0-pre2 released

    + + 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. + +

    + + 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. +

    + + 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. +

    + + 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... +

    + + The changelog has all + the details. As usual you can download busybox here. + +

    Have Fun! +

    + +

    +

  • 15 July 2003 -- BusyBox 1.0.0-pre1 released

    + + 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... +

    + + 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. +

    + + 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 NOT 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. +

    + + 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. +

    + + As usual you can download busybox here. + You don't really need to bother with the + changelog, 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. + +

    Have Fun! +

    + + + +

    +

  • 26 October 2002 -- BusyBox 0.60.5 released

    + + 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... + +

    + The changelog has all + the details. As usual you can download busybox here. +

    Have Fun! +

    + +

    +

  • 18 September 2002 -- BusyBox 0.60.4 released

    + + 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. + +

    + The changelog has all + the details. As usual you can download busybox here. +

    Have Fun! +

    + + +

    +

  • 27 April 2002 -- BusyBox 0.60.3 released

    + + 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. + +

    + The changelog has all + the details. As usual you can download busybox here. +

    Have Fun! +

    + + +

    +

  • 6 March 2002 -- busybox.net now has mirrors!

    + + Busybox.net is now much more available, thanks to + the fine folks at http://i-netinnovations.com/ + who are providing hosting for busybox.net and + uclibc.org. In addition, we now have two mirrors: + http://busybox.linuxmagic.com/ + in Canada and + http://busybox.csservers.de/ + in Germany. I hope this makes things much more + accessible for everyone! + + +

  • +3 January 2002 -- Welcome to busybox.net! + +

    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).

    + +

    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, Mark Whitley +(author of busybox sed, cut, and grep) has donated +his NetWinder 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.

    + +

    + 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 HUGE thank-you goes out to +everyone that has contributed!
    + -Erik

    +
    • + +
  • +20 November 2001 -- BusyBox 0.60.2 released + +

    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.

    + +

    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 changelog for most +of the details. The last release was +very solid for people, and this one should +be even better.

    + +

    As usual BusyBox 0.60.2 can be downloaded from +http://www.busybox.net/downloads.

    + +

    Have Fun.
    + -Erik

    +
    • + +
  • 18 November 2001 -- Help us buy busybox.net! + + +
    +Click here to help buy busybox.net! +
    + + + + + + +
    +
    + + +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 know 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. +

    + +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... +

    + +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! +

    + + +

  • 23 August 2001 -- BusyBox 0.60.1 released +
    + + 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 too + 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. +

    + The + changelog has all + the details. As usual BusyBox 0.60.1 can be downloaded from + http://busybox.net/downloads. +

    Have Fun! +

    + + +

  • 2 August 2001 -- BusyBox 0.60.0 released +
    + I am very pleased to announce the immediate availability of + BusyBox 0.60.0. I have personally tested this release with libc5, glibc, + and uClibc 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. + +

    + + Those wanting an easy way to test the 0.60.0 release with uClibc can + use User-Mode Linux + to give it a try by downloading and compiling + buildroot.tar.gz. + 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. +

    + Another cool thing is the nifty + BusyBox Tutorial contributed by K Computing. This requires + a ShockWave plugin (or standalone viewer), so you may want to grab the + the GPLed shockwave viewer from here + to view the tutorial. +

    + + Finally, In case you didn't notice anything odd about the + version number of this release, let me point out that this release + is not 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. + +

    + The + changelog has all + the details. As usual BusyBox 0.60.0 can be downloaded from + http://busybox.net/downloads. +

    Have Fun! +

    + + +

  • 7 July 2001 -- BusyBox 0.52 released +
    + + 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 many 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). + +

    + The + changelog 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 + http://busybox.net/downloads. +

    Have Fun! +

    + + +

  • 10 April 2001 - Graph of Busybox Growth +
    +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 right here. + +

    (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.) +

    + + +

  • 10 April 2001 -- BusyBox 0.51 released +
    + + 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. +

    + + 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!). +

    + You can read the + changelog for + complete details. BusyBox 0.51 can be downloaded from + http://busybox.net/downloads. +

    Have Fun! +

    + +

  • Busybox Boot-Floppy Image + +

    Because you asked for it, we have made available a Busybox boot floppy +image. Here's how you use it: + +

      + +
    1. + Download the image + +
    2. dd it onto a floppy like so: dd if=busybox.floppy.img + of=/dev/fd0 ; sync + +
    3. Pop it in a machine and boot up. + +
    + +

    If you want to look at the contents of the initrd image, do this: + +

    +    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
+
    + + +
  • 15 March 2001 -- BusyBox 0.50 released +
    + + 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 + changelog. +

    + 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 + Larry Doolittle's website. +

    + + +

  • 27 January 2001 -- BusyBox 0.49 released +
    + + 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 changelog. +

    + 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. +

    + Special Note
    + + 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 Larry's website + and help out if you can. This shell will be included in the next + release of BusyBox. +

    + +

  • 13 December 2000 -- BusyBox 0.48 released +
    + + 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. +

    + The curious can get a list of some of the more interesting changes by reading + the changelog. +

    + Many thanks go out to the many many people that have contributed to + this release, especially Matt Kraai, Larry Doolittle, and Kent Robotti. +

    +

  • 26 September 2000 -- BusyBox 0.47 released +
    + + 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 changelog + for complete details. + + +

  • 11 July 2000 -- BusyBox 0.46 released +
    + + 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 changelog + for complete details. + + +

  • 21 June 2000 -- BusyBox 0.45 released +
    + + 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 changelog for + details). +

    + Also, some exciting infrastructure news! Busybox now has its own + mailing list, + publically browsable + CVS tree, + anonymous + CVS access, and + for those that are actively contributing there is even + CVS write access. + I think this will be a huge help to the ongoing development of BusyBox. +

    + 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. +

    + Many thanks go out to the many people that have contributed to this release + of BusyBox (esp. Pavel Roskin)! + + +

  • 19 April 2000 -- syslogd bugfix +
    +Turns out that there was still a bug in busybox syslogd. +For example, with the following test app: +
    +#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);
+}
+
    +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). +

    +Karl M. Hegbloom has created a fix for the problem. +Thanks Karl! + + +

  • 18 April 2000 -- BusyBox 0.43 released (finally!) +
    +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 +changelog. +Oh, and as a special bonus, I wrote some fairly comprehensive +documentation, complete with examples and full usage information. + +

    +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. +

    + +You can grab BusyBox 0.43 tarballs here. + +

  • 9 April 2000 -- BusyBox 0.43 pre release +
    +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. +

    +The pre-release can be found here. +Please let me know ASAP if you find any bugs. + +

  • 28 March 2000 -- Andersen Baby Boy release +
    +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). +

    +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. +

    +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. + + +

  • 11 February 2000 -- BusyBox 0.42 released +
    + + This is the most solid BusyBox release so far. Many, many + bugs have been fixed. See the + changelog 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. + +

  • 19 January 2000 -- BusyBox 0.41 released +
    + + 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 here. + +

  • 7 January 2000 -- BusyBox 0.40 released +
    + + 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 here. + +

  • 11 December 1999 -- BusyBox Website +
    + 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. + +

  • 10 December 1999 -- BusyBox 0.39 released +
    + 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 here. +

  • 5 December 1999 -- BusyBox 0.38 released +
    + This release includes fixes to tar, cat, ls, dd, rm, umount, find, df, + and make install, and includes new apps syslogd/klogd and logger. + + +
+ + + + 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 @@ + + + +

Products/Projects Using BusyBox

+ +Do you use BusyBox? I'd love to know about it and +I'd be happy to link to you. + +

+I know of the following projects that use BusyBox -- +listed in the order I happen to add them to the web page: + +

+ +

+And here are products that use BusyBox -- + +

+ + 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 @@ + + + + + +

Busybox Screenshot!

+ + +Everybody loves to look at screenshots, so here is a live action screenshot of BusyBox. + +
+
+$ 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
+
+$ _
+
+
+ + 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 @@ + + + +

Hall of Shame!!!

+ +

This page is no longer updated, these days we forward this sort of +thing to the Software Freedom Law +Center instead.

+ +

The following products and/or projects appear to use BusyBox, but do not +appear to release source code as required by the BusyBox license. This is a violation of the law! +The distributors of these products are invited to contact Erik Andersen 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. + +

+ +Here are the details of exactly how to comply +with the BusyBox license, 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 Erik 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. + +

+ +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. + +

+ +

+ + + + 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 @@ + + +

Sponsors

+ +

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!

+ + + + +

If you wish to be a sponsor, or if you have already contributed and would +like your name added here, email Denys.

+ + 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 @@ + + +

Accessing Source

+ + + +

Patches

+ +

You can download fixes for particular releases +of busybox, e.g. downloads/fixes-major-minor-patch/ + +

Anonymous Subversion Access

+ +We allow anonymous (read-only) Subversion (svn) access to everyone. To +grab a copy of the latest version of BusyBox using anonymous svn access: + +
+svn co svn://busybox.net/trunk/busybox
+ +

+The current stable branch can be obtained with +

+svn co svn://busybox.net/branches/busybox_1_12_stable
+
+ +

+ +If you are not already familiar with using Subversion, I recommend you visit the Subversion website. You might +also want to read online or buy a copy of the Subversion Book. If you are +already comfortable with using CVS, you may want to skip ahead to the Subversion for CVS Users +part of the Subversion Book. + +

+ +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: + +

+svn update
+ +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 +Subversion commit access can be made available. + + + 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 @@ + + + +

External Tiny Utilities

+ +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. + +

+ + + + + + + + + + + + + + + + + + + + +
FeatureUtilities
SSHDropbear 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.
SMTPssmtp is an extremely simple Mail Transfer Agent.
ntpntpclient 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.
+ +

In a gui environment, you'll probably want a web browser. +Konqueror Embedded requires QT +(or QT Embedded), but not KDE. The Dillo +requires GTK+, but not Gnome. Or you can try the graphical +version of links.

+ +

SCRIPTING LANGUAGES

+

Although busybox has built-in support for shell scripts, plenty of other +small scripting languages are available on the net. A few examples:

+ + + + + + + + + + + + + + + + + + + + + + + + +
languagedescription
microperl 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. +
LuaIf you just want a small embedded scripting language to write new +code in, this Brazilian import is lightweight, fairly popular, and has +a complete book about it online.
rcThe PLAN9 shell. Not compatible with conventional bourne shell syntax, +but fairly lightweight and small.
forthA well known language for fast and small programs, decades old but still +in use for everything from OpenBIOS to computer controlled engine timing.
+ +

For more information, you probably want to look at +buildroot and +TinyGentoo, which +build and use tiny utilities for all sorts of things.

+ + + 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 + +=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
+ +Emanuele Aina + run-parts + +=for html
+ +Erik Andersen + + 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
+ +Laurence Anderson + + rpm2cpio, unzip, get_header_cpio, read_gz interface, rpm + +=for html
+ +Jeff Angielski + + ftpput, ftpget + +=for html
+ +Edward Betts + + expr, hostid, logname, whoami + +=for html
+ +John Beppu + + du, nslookup, sort + +=for html
+ +Brian Candler + + tiny-ls(ls) + +=for html
+ +Randolph Chung + + fbset, ping, hostname + +=for html
+ +Dave Cinege + + more(v2), makedevs, dutmp, modularization, auto links file, + various fixes, Linux Router Project maintenance + +=for html
+ +Jordan Crouse + + ipcalc + +=for html
+ +Magnus Damm + + tftp client insmod powerpc support + +=for html
+ +Larry Doolittle + + pristine source directory compilation, lots of patches and fixes. + +=for html
+ +Glenn Engel + + httpd + +=for html
+ +Gennady Feldman + + Sysklogd (single threaded syslogd, IPC Circular buffer support, + logread), various fixes. + +=for html
+ +Karl M. Hegbloom + + cp_mv.c, the test suite, various fixes to utility.c, &c. + +=for html
+ +Daniel Jacobowitz + + mktemp.c + +=for html
+ +Matt Kraai + + documentation, bugfixes, test suite + +=for html
+ +Stephan Linz + + ipcalc, Red Hat equivalence + +=for html
+ +John Lombardo + + tr + +=for html
+ +Glenn McGrath + + Common unarchving code and unarchiving applets, ifupdown, ftpgetput, + nameif, sed, patch, fold, install, uudecode. + Various bugfixes, review and apply numerous patches. + +=for html
+ +Manuel Novoa III + + 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
+ +Vladimir Oleynik + + 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
+ +Bruce Perens + + Original author of BusyBox in 1995, 1996. Some of his code can + still be found hiding here and there... + +=for html
+ +Tim Riker + + bug fixes, member of fan club + +=for html
+ +Kent Robotti + + reset, tons and tons of bug reports and patches. + +=for html
+ +Chip Rosenthal , + + wget - Contributed by permission of Covad Communications + +=for html
+ +Pavel Roskin + + Lots of bugs fixes and patches. + +=for html
+ +Gyepi Sam + + Remote logging feature for syslogd + +=for html
+ +Linus Torvalds + + mkswap, fsck.minix, mkfs.minix + +=for html
+ +Mark Whitley + + grep, sed, cut, xargs(previous), + style-guide, new-applet-HOWTO, bug fixes, etc. + +=for html
+ +Charles P. Wright + + gzip, mini-netcat(nc) + +=for html
+ +Enrique Zanardi + + tarcat (since removed), loadkmap, various fixes, Debian maintenance + +=for html
+ +Tito Ragusa + + 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 [arguments...] # or + + [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 @@ +CGI Command line options

CGI Command line options

+

+ +

Specification

+ +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 QUERY_STRING 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.

+ +For example, use the finger script and the ISINDEX interface to look up "httpd". You will see that the script will call itself with /cgi-bin/finger?httpd and will actually execute "finger httpd" on the command line and output the results to you. +

+If the server does find a "=" in the QUERY_STRING, +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 this hyperlink to submit "httpd=name" to the finger script. Since this QUERY_STRING +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. +

+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 QUERY_STRING.

+

+

Examples

+ +Examples of the command line usage are much better demonstrated than explained. For these +examples, pay close attention to the script output which says what +argc and argv are.

+ +

+ +[Back]Return to the +interface specification

+ +CGI - Common Gateway Interface +

cgi@ncsa.uiuc.edu
+ + + \ 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 @@ +CGI Environment Variables

CGI Environment Variables

+
+ +

+ +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.

+ +

+

Specification

+ +

+The following environment variables are not request-specific and are +set for all requests:

+ +

    +
  • SERVER_SOFTWARE

    + + The name and version of the information server software answering + the request (and running the gateway). Format: name/version

    + +

  • SERVER_NAME

    + The server's hostname, DNS alias, or IP address as it would appear + in self-referencing URLs.

    + +

  • GATEWAY_INTERFACE

    + The revision of the CGI specification to which this server + complies. Format: CGI/revision

    + +

+ +
+ +The following environment variables are specific to the request being +fulfilled by the gateway program:

+ +

    +
  • SERVER_PROTOCOL

    + The name and revision of the information protcol this request came + in with. Format: protocol/revision

    + +

  • SERVER_PORT

    + The port number to which the request was sent.

    + +

  • REQUEST_METHOD

    + The method with which the request was made. For HTTP, this is + "GET", "HEAD", "POST", etc.

    + +

  • PATH_INFO

    + 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.

    + +

  • PATH_TRANSLATED

    + The server provides a translated version of PATH_INFO, which takes + the path and does any virtual-to-physical mapping to it.

    + +

  • SCRIPT_NAME

    + A virtual path to the script being executed, used for + self-referencing URLs.

    + +

  • QUERY_STRING

    + The information which follows the ? in the URL + 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 command line decoding.

    + +

  • REMOTE_HOST

    + The hostname making the request. If the server does not have this + information, it should set REMOTE_ADDR and leave this unset.

    + +

  • REMOTE_ADDR

    + The IP address of the remote host making the request.

    + +

  • AUTH_TYPE

    + If the server supports user authentication, and the script is + protects, this is the protocol-specific authentication method used + to validate the user.

    + +

  • REMOTE_USER

    + If the server supports user authentication, and the script is + protected, this is the username they have authenticated as.

    +

  • REMOTE_IDENT

    + 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. +

    + +

  • CONTENT_TYPE

    + For queries which have attached information, such as HTTP POST and + PUT, this is the content type of the data.

    + +

  • CONTENT_LENGTH

    + The length of the said content as given by the client.

    + +

+ + +
 + +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.

+ +An example of this is the HTTP_ACCEPT variable which was defined in +CGI/1.0. Another example is the header User-Agent.

+ +

    +
  • HTTP_ACCEPT

    + 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.

    + + Format: type/subtype, type/subtype

    + + +

  • HTTP_USER_AGENT

    + + The browser the client is using to send the request. General +format: software/version library/version.

    + +

+ +
+

Examples

+ +Examples of the setting of environment variables are really much better +demonstrated than explained.

+ +

+ +[Back]Return to the +interface specification

+ +CGI - Common Gateway Interface +

cgi@ncsa.uiuc.edu
+ + \ 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 @@ +CGI Script input

CGI Script Input

+
+ +

Specification

+ +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. +

+ +The server will send CONTENT_LENGTH bytes on +this file descriptor. Remember that it will give the CONTENT_TYPE of the data as well. The server is +in no way obligated to send end-of-file after the script reads +CONTENT_LENGTH bytes.

+

+

Example

+ +Let's take a form with METHOD="POST" as an example. Let's say the form +results are 7 bytes encoded, and look like a=b&b=c. +

+ +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.

+ +

+ +[Back]Return to the +interface specification

+ +CGI - Common Gateway Interface +

cgi@ncsa.uiuc.edu
+ + \ 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 @@ +The Common Gateway Interface Specification +[http://hoohoo.ncsa.uiuc.edu/cgi/interface.html] +

The CGI Specification

+ +
+ +This is the specification for CGI version 1.1, or CGI/1.1. Further +revisions of this protocol are guaranteed to be backward compatible. +

+ +The server and the CGI script communicate in four major ways. Each of +the following is a hotlink to graphic detail.

+ +

+
+ + +[Back]Return to the overview

+ + + +CGI - Common Gateway Interface +

cgi@ncsa.uiuc.edu
+ \ 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 @@ +CGI Script output

CGI Script Output

+
+ +

Script output

+ +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.

+

+ +

Script naming conventions

+ +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.

+ +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.

+ +

+

Parsed headers

+ +The output of scripts begins with a small header. This header consists +of text lines, in the same format as an +HTTP header, terminated by a blank line (a line with only a +linefeed or CR/LF).

+ +Any headers which are not server directives are sent directly back to +the client. Currently, this specification defines three server +directives:

+ +

    +
  • Content-type

    + + This is the MIME type of the document you are returning.

    + +

  • Location

    + + This is used to specify to the server that you are returning a + reference to a document rather than an actual document.

    + + If the argument to this is a URL, the server will issue a redirect + to the client.

    + + 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.

    + + +

  • Status

    + + This is used to give the server an HTTP/1.0 status +line to send to the client. The format is nnn xxxxx, +where nnn is the 3-digit status code, and +xxxxx is the reason string, such as "Forbidden".

    + +

+ +
+

Examples

+ +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):

+ +

--- start of output ---
+Content-type: text/html
+
+--- end of output ---
+
+ +Note the blank line after Content-type.

+ +Now, let's say I have a script which, in certain instances, wants to +return the document /path/doc.txt from this server just +as if the user had actually requested +http://server:port/path/doc.txt to begin with. In this +case, the script would output:

+

--- start of output ---
+Location: /path/doc.txt
+
+--- end of output ---
+
+ +The server would then perform the request and send it to the client. +

+ +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 +gopher://gopher.ncsa.uiuc.edu/, it would output:

+ +

--- start of output ---
+Location: gopher://gopher.ncsa.uiuc.edu/
+
+--- end of output ---
+
+ +Finally, I have a script which wants to talk to the client directly. +In this case, if the script is referenced with SERVER_PROTOCOL of HTTP/1.0, +the script would output the following HTTP/1.0 response:

+ +

--- 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 ---
+
+ + +
+ +[Back]Return to the +interface specification

+ +CGI - Common Gateway Interface +

cgi@ncsa.uiuc.edu
+ \ 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 @@ + + + + The Linux kernel: Processes + + +
+

10. Processes

+ +

Before looking at the Linux implementation, first a general Unix +description of threads, processes, process groups and sessions. +

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. +

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. +

All these objects have numbers, and we have thread IDs, process IDs, +process group IDs and session IDs. +

+

10.1 Processes +

+ +

+

Creation

+ +

A new process is traditionally started using the fork() +system call: +

+
pid_t p;
+
+p = fork();
+if (p == (pid_t) -1)
+        /* ERROR */
+else if (p == 0)
+        /* CHILD */
+else
+        /* PARENT */
+
+
+

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 fork() +returns 0 in the child. (It can find the process ID of its +parent using the getppid() system call.) +

+

Termination

+ +

Normal termination is when the process does +

+
exit(n);
+
+
+ +or +
+
return n;
+
+
+ +from its main() procedure. It returns the single byte n +to its parent. +

Abnormal termination is usually caused by a signal. +

+

Collecting the exit code. Zombies

+ +

The parent does +

+
pid_t p;
+int status;
+
+p = wait(&status);
+
+
+ +and collects two bytes: +

+

+ + + +

A process that has terminated but has not yet been waited for +is a zombie. It need only store these two bytes: +exit code and reason for termination. +

On the other hand, if the parent dies first, init (process 1) +inherits the child and becomes its parent. +

+

Signals

+ +

+

Stopping

+ +

Some signals cause a process to stop: +SIGSTOP (stop!), +SIGTSTP (stop from tty: probably ^Z was typed), +SIGTTIN (tty input asked by background process), +SIGTTOU (tty output sent by background process, and this was +disallowed by stty tostop). +

Apart from ^Z there also is ^Y. The former stops the process +when it is typed, the latter stops it when it is read. +

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.) +

If a process is being traced, every signal will stop it. +

+

Continuing

+ +

SIGCONT: continue a stopped process. +

+

Terminating

+ +

SIGKILL (die! now!), +SIGTERM (please, go away), +SIGHUP (modem hangup), +SIGINT (^C), +SIGQUIT (^\), 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 SIGCHLD and SIGWINCH +are ignored by default. +All except SIGKILL and SIGSTOP can be +caught or ignored or blocked. +For details, see signal(7). +

+

10.2 Process groups +

+ +

Every process is member of a unique process group, +identified by its process group ID. +(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 process group leader. +A process finds the ID of its process group using the system call +getpgrp(), or, equivalently, getpgid(0). +One finds the process group ID of process p using +getpgid(p). +

One may use the command ps j 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 ash, 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 bash, the processes of one pipeline, like +

+
% cat paper | ideal | pic | tbl | eqn | ditroff > out
+
+
+ +form a single process group. +

+

Creation

+ +

A process pid is put into the process group pgid by +

+
setpgid(pid, pgid);
+
+
+ +If pgid == pid or pgid == 0 then this creates +a new process group with process group leader pid. +Otherwise, this puts pid into the already existing +process group pgid. +A zero pid refers to the current process. +The call setpgrp() is equivalent to setpgid(0,0). +

+

Restrictions on setpgid()

+ +

The calling process must be pid itself, or its parent, +and the parent can only do this before pid has done +exec(), and only when both belong to the same session. +It is an error if process pid is a session leader +(and this call would change its pgid). +

+

Typical sequence

+ +

+

+
p = fork();
+if (p == (pid_t) -1) {
+        /* ERROR */
+} else if (p == 0) {    /* CHILD */
+        setpgid(0, pgid);
+        ...
+} else {                /* PARENT */
+        setpgid(p, pgid);
+        ...
+}
+
+
+ +This ensures that regardless of whether parent or child is scheduled +first, the process group setting is as expected by both. +

+

Signalling and waiting

+ +

One can signal all members of a process group: +

+
killpg(pgrp, sig);
+
+
+

One can wait for children in ones own process group: +

+
waitpid(0, &status, ...);
+
+
+ +or in a specified process group: +
+
waitpid(-pgrp, &status, ...);
+
+
+

+

Foreground process group

+ +

Among the process groups in a session at most one can be +the foreground process group of that session. +The tty input and tty signals (signals generated by ^C, ^Z, etc.) +go to processes in this foreground process group. +

A process can determine the foreground process group in its session +using tcgetpgrp(fd), where fd refers to its +controlling tty. If there is none, this returns a random value +larger than 1 that is not a process group ID. +

A process can set the foreground process group in its session +using tcsetpgrp(fd,pgrp), where fd refers to its +controlling tty, and pgrp is a process group in +its session, and this session still is associated to the controlling +tty of the calling process. +

How does one get fd? By definition, /dev/tty +refers to the controlling tty, entirely independent of redirects +of standard input and output. (There is also the function +ctermid() to get the name of the controlling terminal. +On a POSIX standard system it will return /dev/tty.) +Opening the name of the +controlling tty gives a file descriptor fd. +

+

Background process groups

+ +

All process groups in a session that are not foreground +process group are background process groups. +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 fg 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.) +

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 +

+
% stty tostop
+
+
+ +and clear it again by +
+
% stty -tostop
+
+
+ +and inspect it by +
+
% stty -a
+
+
+ +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. +

+

Orphaned process groups

+ +

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. +

A process group is called orphaned when the +parent of every member is either in the process group +or outside the session. +In particular, the process group of the session leader +is always orphaned. +

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. +

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. +

Note that the process group of the session leader is already +orphaned, so no signals are sent when the session leader dies. +

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. +

+

10.3 Sessions +

+ +

Every process group is in a unique session. +(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 session leader. +A process finds the ID of its session using the system call +getsid(). +

Every session may have a controlling tty, +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 /dev/tty. (And when that fails, there was no +controlling tty.) Given a file descriptor for the controlling tty, +one may obtain the SID using tcgetsid(fd). +

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. +

+

Creation

+ +

A new session is created by +

+
pid = setsid();
+
+
+ +This is allowed only when the current process is not a process group leader. +In order to be sure of that we fork first: +
+
p = fork();
+if (p) exit(0);
+pid = setsid();
+
+
+ +The result is that the current process (with process ID pid) +becomes session leader of a new session with session ID pid. +Moreover, it becomes process group leader of a new process group. +Both session and process group contain only the single process pid. +Furthermore, this process has no controlling tty. +

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. +

+

Getting a controlling tty

+ +

How does one get a controlling terminal? Nobody knows, +this is a great mystery. +

The System V approach is that the first tty opened by the process +becomes its controlling tty. +

The BSD approach is that one has to explicitly call +

+
ioctl(fd, TIOCSCTTY, 0/1);
+
+
+ +to get a controlling tty. +

Linux tries to be compatible with both, as always, and this +results in a very obscure complex of conditions. Roughly: +

The TIOCSCTTY 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] +

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 O_NOCTTY 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. +

+

Getting rid of a controlling tty

+ +

If a process wants to continue as a daemon, it must detach itself +from its controlling tty. Above we saw that setsid() +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: +

+

        if ((fork()) != 0)
+                exit(0);
+        setsid();
+        if ((fork()) != 0)
+                exit(0);
+
+

See also daemon(3). +

+

Disconnect

+ +

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 errno set to EIO.) +

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. +

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). +

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. +

+

10.4 Threads +

+ +

A process can have several threads. New threads (with the same PID +as the parent thread) are started using the clone system +call using the CLONE_THREAD flag. Threads are distinguished +by a thread ID (TID). An ordinary process has a single thread +with TID equal to PID. The system call gettid() returns the +TID. The system call tkill() sends a signal to a single thread. +

Example: a process with two threads. Both only print PID and TID and exit. +(Linux 2.4.19 or later.) +

% 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
+%
+
+

+

+

+ + 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 @@ + + + + Common Gateway Interface - 1.1 *Draft 03* [http://cgi-spec.golux.com/draft-coar-cgi-v11-03-clean.html] + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + + + + + + + +
+ INTERNET-DRAFT                                 + +           Ken A L Coar +
+ draft-coar-cgi-v11-03.{html,txt}              + +         IBM Corporation +
+                                                 + +       D.R.T. Robinson +
+                                                 + +       E*TRADE UK Ltd. +
+                                                 + +         25 June 1999 +
+
+ +

+ The WWW Common Gateway Interface +
+ Version 1.1 +

+ + + +

+ + Abstract + +

+

+ 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. +

+

+ 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. +

+

+ Discussion of this draft occurs on the CGI-WG mailing list; see the + project Web page at + <URL:http://CGI-Spec.Golux.Com/> + for details on the mailing list and the status of the project. +

+ + +

+ Revision History +

+

+ 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: +

+
+
Black +
+
Revision 00, released 28 May 1998 +
+
Green +
+
Revision 01, released 28 December 1998 +
+ Major structure change: Section 4, "Request Metadata (Meta-Variables)" + was moved entirely under Section 7, "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 not appear as struckthrough. This has + caused major sections 5 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). +
+
Red +
+
Revision 02, released 2 April, 1999 +
+ Added text to section 8.3 defining correct handling + of HTTP/1.1 + requests using "chunked" Transfer-Encoding. Labelled metavariable + names in section 8 with the appropriate detail section + numbers. + Clarified allowed usage of Status and + Location response header fields. Included new + Internet-Draft language. +
+
Fuchsia +
+
Revision 03, released 25 June 1999 +
+ 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. +
+
+ + +

+ + Table of Contents + +

+
+ 
+  1 Introduction..............................................TBD
+   1.1 Purpose................................................TBD
+   1.2 Requirements...........................................TBD
+   1.3 Specifications.........................................TBD
+   1.4 Terminology............................................TBD
+  2 Notational Conventions and Generic Grammar................TBD
+   2.1 Augmented BNF..........................................TBD
+   2.2 Basic Rules............................................TBD
+  3 Protocol Parameters.......................................TBD
+   3.1 URL Encoding...........................................TBD
+   3.2 The Script-URI.........................................TBD
+  4 Invoking the Script.......................................TBD
+  5 The CGI Script Command Line...............................TBD
+  6 Data Input to the CGI Script..............................TBD
+   6.1 Request Metadata (Metavariables).......................TBD
+    6.1.1 AUTH_TYPE...........................................TBD
+    6.1.2 CONTENT_LENGTH......................................TBD
+    6.1.3 CONTENT_TYPE........................................TBD
+    6.1.4 GATEWAY_INTERFACE...................................TBD
+    6.1.5 Protocol-Specific Metavariables.....................TBD
+    6.1.6 PATH_INFO...........................................TBD
+    6.1.7 PATH_TRANSLATED.....................................TBD
+    6.1.8 QUERY_STRING........................................TBD
+    6.1.9 REMOTE_ADDR.........................................TBD
+    6.1.10 REMOTE_HOST........................................TBD
+    6.1.11 REMOTE_IDENT.......................................TBD
+    6.1.12 REMOTE_USER........................................TBD
+    6.1.13 REQUEST_METHOD.....................................TBD
+    6.1.14 SCRIPT_NAME........................................TBD
+    6.1.15 SERVER_NAME........................................TBD
+    6.1.16 SERVER_PORT........................................TBD
+    6.1.17 SERVER_PROTOCOL....................................TBD
+    6.1.18 SERVER_SOFTWARE....................................TBD
+    6.2 Request Message-Bodies................................TBD
+  7 Data Output from the CGI Script...........................TBD
+   7.1 Non-Parsed Header Output...............................TBD
+   7.2 Parsed Header Output...................................TBD
+    7.2.1 CGI header fields...................................TBD
+     7.2.1.1 Content-Type.....................................TBD
+     7.2.1.2 Location.........................................TBD
+     7.2.1.3 Status...........................................TBD
+     7.2.1.4 Extension header fields..........................TBD
+    7.2.2 HTTP header fields..................................TBD
+  8 Server Implementation.....................................TBD
+   8.1 Requirements for Servers...............................TBD
+    8.1.1 Script-URI..........................................TBD
+    8.1.2 Request Message-body Handling.......................TBD
+    8.1.3 Required Metavariables..............................TBD
+    8.1.4 Response Compliance.................................TBD
+   8.2 Recommendations for Servers............................TBD
+   8.3 Summary of Metavariables...............................TBD
+  9 Script Implementation.....................................TBD
+   9.1 Requirements for Scripts...............................TBD
+   9.2 Recommendations for Scripts............................TBD
+  10 System Specifications....................................TBD
+   10.1 AmigaDOS..............................................TBD
+   10.2 Unix..................................................TBD
+  11 Security Considerations..................................TBD
+   11.1 Safe Methods..........................................TBD
+   11.2 HTTP Header Fields Containing Sensitive Information...TBD
+   11.3 Script Interference with the Server...................TBD
+   11.4 Data Length and Buffering Considerations..............TBD
+   11.5 Stateless Processing..................................TBD
+  12 Acknowledgments..........................................TBD
+  13 References...............................................TBD
+  14 Authors' Addresses.......................................TBD
+
+
+ +

+ + 1. Introduction + +

+ +

+ + 1.1. Purpose + +

+

+ Together the HTTP [3,8] 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) + [1], a + request method, and various ancillary + information about the request + provided by the transport mechanism. +

+

+ 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. +

+ +

+ + 1.2. Requirements + +

+

+ This specification uses the same words as RFC 1123 + [5] to define the + significance of each particular requirement. These are: +

+

+
+
MUST +
+
+

+ This word or the adjective 'required' means that the item is an + absolute requirement of the specification. +

+
+
SHOULD +
+
+

+ 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. +

+
+
MAY +
+
+

+ 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. +

+
+
+

+ 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.' +

+ +

+ + 1.3. Specifications + +

+

+ 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: +

+
+
system defined +
+
+

+ 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 + section 10 of this document. + New systems may be defined + by new specifications without revision of this document. +

+
+
implementation defined +
+
+

+ The behaviour of the feature may vary from implementation to + implementation, but a particular implementation must document its + behaviour. +

+
+
+ +

+ + 1.4. Terminology + +

+

+ This specification uses many terms defined in the HTTP/1.1 + specification [8]; 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. +

+ +
+
metavariable +
+
+

+ 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. +

+
+ +
script +
+
+

+ The software which is invoked by the server via 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 may 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. +

+
+
server +
+
+

+ The application program which invokes the script in order to service + requests. +

+
+
+ +

+ + 2. Notational Conventions and Generic Grammar + +

+ +

+ + 2.1. Augmented BNF + +

+

+ 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 [6]. This augmented BNF contains + the following constructs: +

+
+
name = definition +
+
+

+ The + definition by the equal character ("="). Whitespace is only + significant in that continuation lines of a definition are + indented. +

+
+
"literal" +
+
+

+ 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. +

+
+
rule1 | rule2 +
+
+

+ Alternative rules are separated by a vertical bar ("|"). +

+
+
(rule1 rule2 rule3) +
+
+

+ Elements enclosed in parentheses are treated as a single element. +

+
+
*rule +
+
+

+ 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. +

+
+
[rule] +
+
+

+ An element enclosed in square + brackets ("[" and "]") is optional. +

+
+
+ +

+ + 2.2. Basic Rules + +

+

+ The following rules are used throughout this specification to + describe basic parsing constructs. +

+

+ 
+    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
+
+

+ Note that newline (NL) need not be a single character, but can be a + character sequence. +

+ +

+ + 3. Protocol Parameters + +

+ +

+ + 3.1. URL Encoding + +

+

+ Some variables and constructs used here are described as being + 'URL-encoded'. This encoding is described in section + 2 of RFC + 2396 + [4]. +

+

+ 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. +

+

+ 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: +

+

+ 
+    http://somehost.com/somedir%2Fvalue
+    http://somehost.com/somedir/value
+
+

+ See section + 2 of RFC + 2396 [4] + for authoritative treatment of this issue. +

+ +

+ + 3.2. The Script-URI + +

+

+ 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. +

+

+ The Script-URI has the syntax of generic-RL as defined in section 2.1 + of RFC 1808 [7], with the exception that object + parameters and + fragment identifiers are not permitted: +

+

+ 
+    <scheme>://<host><port>/<path>?<query>
+
+

+ The various components of the + Script-URI + are defined by some of the + metavariables (see + section 4 + below); +

+

+ 
+    script-uri = protocol "://" SERVER_NAME ":" SERVER_PORT enc-script
+                 enc-path-info "?" QUERY_STRING
+
+

+ 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 + section 4.6 for more information about the PATH_INFO + metavariable. +

+

+ Note that the scheme and the protocol are not identical; + for instance, a resource accessed via an SSL mechanism + may have a Client-URI with a scheme of "https" + rather than "http". CGI/1.1 provides no means + for the script to reconstruct this, and therefore + the Script-URI includes the base protocol used. +

+ +

+ + 4. Invoking the Script + +

+

+ The + script is invoked in a system defined manner. Unless specified + otherwise, the file containing the script will be invoked as an + executable program. +

+ +

+ + 5. The CGI Script Command Line + +

+

+ 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: +

+

+ 
+    search-string = search-word *( "+" search-word )
+    search-word   = 1*schar
+    schar         = xunreserved | escaped | xreserved
+    xunreserved   = alpha | digit | xsafe | extra
+    xsafe         = "$" | "-" | "_" | "."
+    xreserved     = ";" | "/" | "?" | ":" | "@" | "&"
+
+

+ 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. +

+

+ 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. +

+

+ 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. +

+ +

+ + 6. Data Input to the CGI Script + +

+

+ 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. +

+ +

+ + 6.1. Request Metadata + (Metavariables) + +

+

+ 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. +

+

+ 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. +

+

+ 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. +

+

+ Metavariable + values MUST be + considered case-sensitive except as noted + otherwise. +

+

+ The canonical + metavariables + defined by this specification are: +

+

+ 
+    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
+
+

+ Metavariables with names beginning with the protocol name (e.g., + "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 section 6.1.5.) +

+ +

+ + 6.1.1. AUTH_TYPE + +

+

+ This variable is specific to requests made + via the + "http" + scheme. +

+

+ If the Script-URI + required access authentication for external + access, then the server + MUST set + the value of + this variable + from the 'auth-scheme' token in + the request's "Authorization" header + field. + Otherwise + it is + set to NULL. +

+

+ 
+    AUTH_TYPE   = "" | auth-scheme
+    auth-scheme = "Basic" | "Digest" | token
+
+

+ HTTP access authentication schemes are described in section 11 of the + HTTP/1.1 specification [8]. The auth-scheme is + not case-sensitive. +

+

+ Servers + MUST + provide this metavariable + to scripts if the request + header included an "Authorization" field + that was authenticated. +

+ +

+ + 6.1.2. CONTENT_LENGTH + +

+

+ 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 "Content-Length" header field (section 14.14, HTTP/1.1 + specification [8]). +

+

+ 
+    CONTENT_LENGTH = "" | 1*digit
+
+

+ Servers MUST provide this metavariable + to scripts if the request + was accompanied by a + message-body entity. +

+ +

+ + 6.1.3. CONTENT_TYPE + +

+

+ If the request includes a + message-body, + CONTENT_TYPE is set + to + the Internet Media Type + [9] of the attached + entity if the type was provided via + a "Content-type" field in the + request header, or if the server can determine it in the absence + of a supplied "Content-type" field. The syntax is the + same as for the HTTP + "Content-Type" header field. +

+

+ 
+    CONTENT_TYPE = "" | media-type
+    media-type   = type "/" subtype *( ";" parameter)
+    type         = token
+    subtype      = token
+    parameter    = attribute "=" value
+    attribute    = token
+    value        = token | quoted-string
+
+

+ 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 [8]. +

+

+ Example: +

+

+ 
+    application/x-www-form-urlencoded
+
+

+ 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 + application/octet-stream + or reject the request with a 415 ("Unsupported Media Type") + error. See section 7.2.1.3 + for more information about returning error status values. +

+

+ Servers MUST provide this metavariable + to scripts if + a "Content-Type" field was present + in the original request header. If the server receives a request + with an attached entity but no "Content-Type" + header field, it MAY attempt to + determine the correct datatype, or it MAY omit this + metavariable when + communicating the request information to the script. +

+ +

+ + 6.1.4. GATEWAY_INTERFACE + +

+

+ This + metavariable + is set to + the dialect of CGI being used + by the server to communicate with the script. + Syntax: +

+

+ 
+    GATEWAY_INTERFACE = "CGI" "/" major "." minor
+    major             = 1*digit
+    minor             = 1*digit
+
+

+ 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. +

+

+ This document defines the 1.1 version of the CGI interface + ("CGI/1.1"). +

+

+ Servers MUST provide this metavariable + to scripts. +

+ +

+ + 6.1.5. Protocol-Specific Metavariables + +

+

+ These metavariables are specific to + the protocol + via which the request is made. + Interpretation of these variables depends on the value of + the + SERVER_PROTOCOL + metavariable + (see + section 6.1.17). +

+

+ 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. + +

+

+ 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 + "Authorization", or + which are available to the script + via other metavariables, + such as "Content-Length" and "Content-Type". +

+ +

+ + 6.1.6. PATH_INFO + +

+

+ 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 + [4]), with the exception + that a PATH_INFO of "/" + represents a single void path segment. +

+

+ 
+    PATH_INFO = "" | ( "/" path )
+    path      = segment *( "/" segment )
+    segment   = *pchar
+    pchar     = <any CHAR except "/">
+
+

+ The PATH_INFO string is the trailing part of the <path> component of + the Script-URI + (see section 3.2) + that follows the SCRIPT_NAME + portion of the path. +

+

+ 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. +

+

+ 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. +

+ +

+ + 6.1.7. PATH_TRANSLATED + +

+

+ PATH_TRANSLATED is derived by taking any path-info component of the + request URI (see + section 6.1.6), decoding it + (see section 3.1), 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. +

+

+ 
+    PATH_TRANSLATED = *CHAR
+
+

+ For a request such as the following: +

+

+ 
+    http://somehost.com/cgi-bin/somescript/this%2eis%2epath%2einfo
+
+

+ the PATH_INFO component would be decoded, and the result + parsed as though it were a request for the following: +

+

+ 
+    http://somehost.com/this.is.the.path.info
+
+

+ This would then be translated to a + location in the server's document repository, + perhaps a filesystem path something + like this: +

+

+ 
+    /usr/local/www/htdocs/this.is.the.path.info
+
+

+ The result of the translation is the value of PATH_TRANSLATED. +

+

+ 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. +

+

+ The + translation + algorithm the server uses to derive PATH_TRANSLATED is + implementation defined; CGI scripts which use this variable may + suffer limited portability. +

+

+ Servers SHOULD provide this metavariable + to scripts if and only if the request URI includes a + path-info component. +

+ +

+ + 6.1.8. QUERY_STRING + +

+

+ A URL-encoded + string; the <query> part of the + Script-URI. + (See + section 3.2.) +

+

+ 
+    QUERY_STRING = query-string
+    query-string = *uric
+
+

+ The URL syntax for a query + string is described in + section 3 of + RFC 2396 + [4]. +

+

+ 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 (""). +

+ +

+ + 6.1.9. REMOTE_ADDR + +

+

+ 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). +

+

+ 
+    REMOTE_ADDR  = hostnumber
+    hostnumber   = ipv4-address | ipv6-address
+
+

+ The definitions of ipv4-address and ipv6-address + are provided in Appendix B of RFC 2373 [13]. +

+

+ Servers MUST supply this value to scripts. +

+ +

+ + 6.1.10. REMOTE_HOST + +

+

+ The fully qualified domain name of the + client sending the request to + the server, if available, otherwise NULL. + (See section 6.1.9.) + Fully qualified domain names take the form as described in + section 3.5 of RFC 1034 [10] and section 2.1 of + RFC 1123 [5]. Domain names are not case sensitive. +

+

+ Servers SHOULD provide this information to + scripts. +

+ +

+ + 6.1.11. REMOTE_IDENT + +

+

+ The identity information reported about the connection by a + RFC 1413 [11] request to the remote agent, if + available. Servers + MAY choose not + to support this feature, or not to request the data + for efficiency reasons. +

+

+ 
+    REMOTE_IDENT = *CHAR
+
+

+ The data returned + may be used for authentication purposes, but the level + of trust reposed in them should be minimal. +

+

+ Servers MAY supply this information to scripts if the + RFC1413 [11] lookup is performed. +

+ +

+ + 6.1.12. REMOTE_USER + +

+

+ If the request required authentication using the "Basic" + mechanism (i.e., 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. +

+

+ 
+    REMOTE_USER = *OCTET
+
+

+ This variable is specific to requests made via the + HTTP protocol. +

+

+ Servers SHOULD provide this metavariable + to scripts. +

+ +

+ + 6.1.13. REQUEST_METHOD + +

+

+ 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 [3] and + section 5.1.1 of the + HTTP/1.1 specification [8]. +

+

+ 
+    REQUEST_METHOD   = http-method
+    http-method      = "GET" | "HEAD" | "POST" | "PUT" | "DELETE"
+                       | "OPTIONS" | "TRACE" | extension-method
+    extension-method = token
+
+

+ The method is case sensitive. + CGI/1.1 servers MAY choose to process some methods + directly rather than passing them to scripts. +

+

+ This variable is specific to requests made with HTTP. +

+

+ Servers MUST provide this metavariable + to scripts. +

+ +

+ + 6.1.14. SCRIPT_NAME + +

+

+ 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 + [4]). +

+

+ 
+    SCRIPT_NAME = "" | ( "/" [ path ] )
+
+

+ 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 6.1.6 and + 6.1.8) are included + in the SCRIPT_NAME value. +

+

+ Servers MUST provide this metavariable + to scripts. +

+ +

+ + 6.1.15. SERVER_NAME + +

+

+ The SERVER_NAME + metavariable + is set to the + name of the + server, as + derived from the <host> part of the + Script-URI + (see section 3.2). +

+

+ 
+    SERVER_NAME = hostname | hostnumber
+
+

+ Servers MUST provide this metavariable + to scripts. +

+ +

+ + 6.1.16. SERVER_PORT + +

+

+ 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. +

+

+ 
+    SERVER_PORT = 1*digit
+
+

+ If the <port> portion of the script-URI is blank, the actual + port number upon which the request was received MUST be supplied. +

+

+ Servers MUST provide this metavariable + to scripts. +

+ +

+ + 6.1.17. SERVER_PROTOCOL + +

+

+ 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. +

+

+ 
+    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
+
+

+ '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 + "https" while the protocol remains "http". + The protocol is not case sensitive, but + by convention, 'protocol' is in + upper case. +

+

+ 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. +

+

+ Servers MUST provide this metavariable + to scripts. +

+ +

+ + 6.1.18. SERVER_SOFTWARE + +

+

+ The SERVER_SOFTWARE + metavariable + is set to the + name and version of the information server software answering the + request (and running the gateway). +

+

+ 
+    SERVER_SOFTWARE = 1*product
+    product         = token [ "/" product-version ]
+    product-version = token
+
+

+ Servers MUST provide this metavariable + to scripts. +

+ +

+ + 6.2. Request Message-Bodies + +

+

+ 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 via the 'standard input' file + descriptor. +

+

+ If the CONTENT_LENGTH value (see section 6.1.2) + 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. +

+

+ For non-parsed header (NPH) scripts (see + section 7.1 + 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. +

+

+ Section 8.1.2 describes the requirements of + servers with regard to requests that include + message-bodies. +

+ +

+ + 7. Data Output from the CGI Script + +

+

+ 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 via the 'standard + output' file descriptor. +

+

+ 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. +

+

+ 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. +

+ +

+ + 7.1. Non-Parsed Header Output + +

+

+ Scripts using the NPH output form + MUST return a complete HTTP response message, as described + in Section 6 of the HTTP specifications + [3,8]. + NPH scripts + MUST use the SERVER_PROTOCOL variable to determine the appropriate format + for a response. +

+

+ Servers + SHOULD attempt to ensure that the script output is sent + directly to the client, with minimal + internal and no transport-visible + buffering. +

+ +

+ + 7.2. Parsed Header Output + +

+

+ Scripts using the parsed header output form MUST supply + a CGI response message to the server + as follows: +

+

+ 
+    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
+
+

+ 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 "Content-type" + header field MUST be + supplied by the script, + otherwise the script MUST send a "Location" + or "Status" header field. If a + Location CGI-Field + is returned, then the script MUST NOT supply + any HTTP-Fields. +

+

+ Each header field in a CGI-Response MUST be specified on a single line; + CGI/1.1 does not support continuation lines. +

+ +

+ + 7.2.1. CGI header fields + +

+

+ The CGI header fields have the generic syntax: +

+

+ 
+    generic-field  = field-name ":" [ field-value ] NL
+    field-name     = token
+    field-value    = *( field-content | LWSP )
+    field-content  = *( token | tspecial | quoted-string )
+
+

+ The field-name is not case sensitive; a NULL field value is + equivalent to the header field not being sent. +

+ +

+ + 7.2.1.1. Content-Type + +

+

+ The Internet Media Type [9] of the entity + body, which is to be sent unmodified to the client. +

+

+ 
+    Content-Type = "Content-Type" ":" media-type NL
+
+

+ 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. +

+ +

+ + 7.2.1.2. Location + +

+

+ This is used to specify to the server that the script is returning a + reference to a document rather than an actual document. +

+

+ 
+    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
+                       | ":" | "@" | "& | "="
+
+

+ The Location + value is either an absolute URI with optional fragment, + as defined in RFC 1630 [1], or an absolute path + within the server's URI space (i.e., + 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 +

+

+ 
+    scheme "://" SERVER_NAME ":" SERVER_PORT rel-URL-abs-path
+
+

+ 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. +

+ +

+ + 7.2.1.3. Status + +

+

+ The "Status" header field is used to indicate to the server what + status code the server MUST use in the response message. +

+

+ 
+    Status        = "Status" ":" digit digit digit SP reason-phrase NL
+    reason-phrase = *<CHAR, excluding CTLs, NL>
+
+

+ The valid status codes are listed in section 6.1.1 of the HTTP/1.0 + specifications [3]. If the SERVER_PROTOCOL is + "HTTP/1.1", then the status codes defined in the HTTP/1.1 + specification [8] may + be used. If the script does not return a "Status" header + field, then "200 OK" SHOULD be assumed by the server. +

+

+ 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 "Status" CGI header field to propagate the error + condition back to the client. E.g., in the example mentioned it + SHOULD include a "Status: 404 Not Found" in the + header data returned to the server. +

+ +

+ + 7.2.1.4. Extension header fields + +

+

+ 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 generic-field as defined in + section 7.2.1. 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. +

+ +

+ + 7.2.2. HTTP header fields + +

+

+ The script MAY return any other header fields defined by the + specification + for the SERVER_PROTOCOL (HTTP/1.0 [3] or HTTP/1.1 + [8]). + Servers MUST resolve conflicts beteen CGI header + and HTTP header formats or names (see section 8). +

+ +

+ + 8. Server Implementation + +

+

+ 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. +

+ +

+ + 8.1. Requirements for Servers + +

+

+ 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. +

+ +

+ + 8.1.1. Script-URI + +

+

+ 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: +

+

+ 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. +

+ +

+ + 8.1.2. Request Message-body Handling + +

+

+ These are the requirements for server handling of message-bodies directed + to CGI/1.1 resources: +

+
    +
  1. The message-body the server provides to the CGI script MUST + have any transfer encodings removed. +
    2. +
  2. 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. +
    3. +
  3. The server MUST leave intact any content-encodings of the message-body. +
    4. +
+ +

+ + 8.1.3. Required Metavariables + +

+

+ Servers MUST provide scripts with certain information and + metavariables + as described in section 8.3. +

+ +

+ + 8.1.4. Response Compliance + +

+

+ 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. +

+ +

+ + 8.2. Recommendations for Servers + +

+

+ Servers SHOULD provide the "query" 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 section 5.) +

+

+ Servers SHOULD set the AUTH_TYPE + metavariable to the value of the + 'auth-scheme' token of the "Authorization" + field if it was supplied as part of the request header. + (See section 6.1.1.) +

+

+ Where applicable, servers SHOULD set the current working directory + to the directory in which the script is located before invoking + it. +

+

+ 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. +

+

+ 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: +

+
    +
  1. define any restrictions on allowed characters, in particular + whether ASCII NUL is permitted; +
    2. +
  2. define any restrictions on allowed path segments, in particular + whether non-terminal NULL segments are permitted; +
    3. +
  3. define the behaviour for "." or ".." path + segments; i.e., whether they are prohibited, treated as + ordinary path + segments or interpreted in accordance with the relative URL + specification [7]; +
    4. +
  4. 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. +
    5. +
+

+ Servers MAY generate the + Script-URI in + any way from the client URI, + or from any other data (but the behaviour SHOULD be documented). +

+

+ For non-parsed header (NPH) scripts (see + section 7.1), 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. +

+ +

+ + 8.3. Summary of + MetaVariables + +

+

+ Servers MUST provide the following + metavariables to + scripts. See the individual descriptions for exceptions and semantics. +

+

+ 
+    CONTENT_LENGTH (section 6.1.2)
+    CONTENT_TYPE (section 6.1.3)
+    GATEWAY_INTERFACE (section 6.1.4)
+    PATH_INFO (section 6.1.6)
+    QUERY_STRING (section 6.1.8)
+    REMOTE_ADDR (section 6.1.9)
+    REQUEST_METHOD (section 6.1.13)
+    SCRIPT_NAME (section 6.1.14)
+    SERVER_NAME (section 6.1.15)
+    SERVER_PORT (section 6.1.16)
+    SERVER_PROTOCOL (section 6.1.17)
+    SERVER_SOFTWARE (section 6.1.18)
+
+

+ Servers SHOULD define the following + metavariables for scripts. + See the individual descriptions for exceptions and semantics. +

+

+ 
+    AUTH_TYPE (section 6.1.1)
+    REMOTE_HOST (section 6.1.10)
+
+

+ 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. +

+

+ Servers MAY define the following + metavariables. See the individual + descriptions for exceptions and semantics. +

+

+ 
+    PATH_TRANSLATED (section 6.1.7)
+    REMOTE_IDENT (section 6.1.11)
+    REMOTE_USER (section 6.1.12)
+
+

+ 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_" (e.g., + "X_DBA") to avoid the potential for such conflicts. +

+ +

+ + 9. + Script Implementation + +

+

+ 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. +

+ +

+ + 9.1. Requirements for Scripts + +

+

+ Scripts using the parsed-header method to communicate with servers + MUST supply a response header to the server. + (See section 7.) +

+

+ 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 section 7.1.) +

+

+ Scripts MUST check the value of the REQUEST_METHOD + metavariable in order + to provide an appropriate response. + (See section 6.1.13.) +

+

+ 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 section 3.1.) +

+

+ Scripts MUST ignore leading zeros in the major and minor version numbers + in the GATEWAY_INTERFACE + metavariable value. (See + section 6.1.4.) +

+

+ When processing requests that include a + message-body, scripts + MUST NOT read more than CONTENT_LENGTH bytes from the input stream. + (See sections 6.1.2 and 6.2.) +

+ +

+ + 9.2. Recommendations for Scripts + +

+

+ Servers may interrupt or terminate script execution at any time + and without warning, so scripts SHOULD be prepared to deal with + abnormal termination. +

+

+ 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. +

+

+ If a script is processing the output of a form, it SHOULD + verify that the CONTENT_TYPE + is "application/x-www-form-urlencoded" [2] + or whatever other media type is expected. +

+

+ Scripts parsing PATH_INFO, + PATH_TRANSLATED, or SCRIPT_NAME + SHOULD be careful + of void path segments ("//") and special path segments + ("." and + ".."). They SHOULD either be removed from the path before + use in OS + system calls, or the request SHOULD be rejected with + '404 Not Found'. +

+

+ 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 "text/html" + documents containing + relative URL links without including a "<BASE>" + tag in the document. +

+

+ When returning header fields, + scripts SHOULD try to send the CGI + header fields (see section + 7.2) as soon as possible, and + SHOULD send them + before any HTTP header fields. This may + help reduce the server's memory requirements. +

+ +

+ + 10. System Specifications + +

+ +

+ + 10.1. AmigaDOS + +

+

+ 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. +

+
+
Environment variables +
+
+

+ These are accessed by the DOS library routine GetVar. The + flags argument SHOULD be 0. Case is ignored, but upper case is + recommended for compatibility with case-sensitive systems. +

+
+
The current working directory +
+
+

+ The current working directory for the script is set to the directory + containing the script. +

+
+
Character set +
+
+

+ 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. +

+
+
+ +

+ + 10.2. Unix + +

+

+ 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. +

+

+ For Unix compatible operating systems, the following are defined: +

+
+
Environment variables +
+
+

+ These are accessed by the C library routine getenv. +

+
+
The command line +
+
+

+ This is accessed using the + argc and argv + arguments to main(). 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. +

+
+
The current working directory +
+
+

+ The current working directory for the script + SHOULD be set to the directory + containing the script. +

+
+
Character set +
+
+

+ 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. +

+
+
+ +

+ + 11. Security Considerations + +

+ +

+ + 11.1. Safe Methods + +

+

+ As discussed in the security considerations of the HTTP + specifications [3,8], 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. +

+

+ CGI scripts are responsible for enforcing any HTTP security considerations + [3,8] + 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. +

+ +

+ + 11.2. HTTP Header + Fields Containing Sensitive Information + +

+

+ 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 + "Basic" + authentication scheme, then the client will send an + "Authorization" + 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 via the HTTP_AUTHORIZATION + metavariable + without careful consideration. + This also applies to the + Proxy-Authorization header field and the corresponding + HTTP_PROXY_AUTHORIZATION + metavariable. +

+ +

+ + 11.3. Script + Interference with the Server + +

+

+ 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. +

+

+ 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. +

+ +

+ + 11.4. Data Length and Buffering Considerations + +

+

+ 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). +

+ +

+ + 11.5. Stateless Processing + +

+

+ 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. +

+

+ 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 (e.g., hidden + HTML form elements, cookies, embedded URLs, etc.). +

+ +

+ + 12. Acknowledgements + +

+

+ 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 www-talk 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. +

+

+ This document has also greatly benefited from the comments and + suggestions made by Chris Adie, Dave Kristol, + Mike Meyer, David Morris, Jeremy Madea, + Patrick McManus, Adam Donahue, + Ross Patterson, and Harald Alvestrand. +

+ +

+ + 13. References + +

+
+
[1] +
+
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. +

+

+
+
[2] +
+
Berners-Lee, T. and Connolly, D., 'Hypertext Markup Language - + 2.0', RFC 1866, MIT/W3C, November 1995. +

+

+
+
[3] +
+
Berners-Lee, T., Fielding, R. T. and Frystyk, H., + 'Hypertext Transfer Protocol -- HTTP/1.0', RFC 1945, MIT/LCS, + UC Irvine, May 1996. +

+

+
+ +
[4] +
+
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. +

+

+
+ +
[5] +
+
Braden, R., Editor, 'Requirements for Internet Hosts -- + Application and Support', STD 3, RFC 1123, IETF, October 1989. +

+

+
+
[6] +
+
Crocker, D.H., 'Standard for the Format of ARPA Internet Text + Messages', STD 11, RFC 822, University of Delaware, August 1982. +

+

+
+
[7] +
+
Fielding, R., 'Relative Uniform Resource Locators', RFC 1808, + UC Irvine, June 1995. +

+

+
+
[8] +
+
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. +

+

+
+
[9] +
+
Freed, N. and Borenstein N., 'Multipurpose Internet Mail + Extensions (MIME) Part Two: Media Types', RFC 2046, Innosoft, + First Virtual, November 1996. +

+

+
+
[10] +
+
Mockapetris, P., 'Domain Names - Concepts and Facilities', + STD 13, RFC 1034, ISI, November 1987. +

+

+
+
[11] +
+
St. Johns, M., 'Identification Protocol', RFC 1431, US + Department of Defense, February 1993. +

+

+
+
[12] +
+
'Coded Character Set -- 7-bit American Standard Code for + Information Interchange', ANSI X3.4-1986. +

+

+
+
[13] +
+
Hinden, R. and Deering, S., + 'IP Version 6 Addressing Architecture', RFC 2373, + Nokia, Cisco Systems, + July 1998. +

+

+
+
+ +

+ + 14. Authors' Addresses + +

+
+

+ Ken A L Coar +
+ MeepZor Consulting +
+ 7824 Mayfaire Crest Lane, Suite 202 +
+ Raleigh, NC 27615-4875 +
+ U.S.A. +

+

+ Tel: +1 (919) 254.4237 +
+ Fax: +1 (919) 254.5250 +
+ Email: + Ken.Coar@Golux.Com +

+
+
+

+ David Robinson +
+ E*TRADE UK Ltd +
+ Mount Pleasant House +
+ 2 Mount Pleasant +
+ Huntingdon Road +
+ Cambridge CB3 0RN +
+ UK +

+

+ Tel: +44 (1223) 566926 +
+ Fax: +44 (1223) 506288 +
+ Email: + drtr@etrade.co.uk +

+ + + 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", "", "" }, + { "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 _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__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: + : + or @ : + +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. + : [=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: + : [=path] [@|$|*] + or + : [>path] [@|$|*] +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 _main instead of main. +And be sure to put it in .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 etc...) + + +----begin example code------ + +/* vi: set sw=4 ts=4: */ +/* + * Mini mu implementation for busybox + * + * Copyright (C) [YEAR] by [YOUR NAME] + * + * 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 .c + +----start example code------ + +#include "libbb.h" +#include "other.h" + +int function(char *a) +{ + return *a; +} + +----end example code------ + +Add .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 /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(_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 +_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 @@ + + + +Proper handling of SIGINT/SIGQUIT [http://www.cons.org/cracauer/sigint.html] + + +

Proper handling of SIGINT/SIGQUIT

+ +

+ + + + + +
Abstract: +In UNIX terminal sessions, you usually have a key like +C-c (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. + +

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. + +

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. + + + +

Intended audience: Programmers who implement programs that catch SIGINT/SIGQUIT. +
Programmers who implements shells or shell-like programs that +execute batches of programs. + +

Users who have problems problems getting rid of runaway shell +scripts using Control-C. 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. + + +

Required knowledge: You have to know what it means to catch SIGINT or SIGQUIT and how +processes are waiting for other processes (childs) they spawned. + + +
+ + + +

Basic concepts

+ +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. + +

You may change the key that triggers the signal using +stty and running programs may remap the SIGINT-sending +key at any time they like, without your intervention and without +asking you first. + +

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. + +

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. + +

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. + +

What we try to achieve

+ +The problem is with shell scripts (or similar programs that call +several subprograms one after another). + +

Let us consider the most basic script: +

+#! /bin/sh
+program1
+program2
+
+and the usual run looks like this: +
+$ sh myscript
+[output of program1]
+[output of program2]
+$
+
+ +

Let us assume that both programs do nothing special on SIGINT, they +just exit. + +

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. + +

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. + +

here is what would happen if the shell doesn't do anything: +

+$ 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]
+
+ + +

Consider a more annoying example: +

+#! /bin/sh
+# let's assume there are 300 *.dat files
+for file in *.dat ; do
+	dat2ascii $dat
+done
+
+ +If your shell wouldn't end if the user hits C-c, +C-c would just end one dat2ascii run and +the script would continue. Thus, you had to hit C-c up to +300 times to end this script. + +

Alternatives to do so

+ +

There are several ways to handle abortion of shell scripts when +SIGINT is received while a foreground child runs: + +

+ +
  • As just outlined, the shellscript may just continue, ignoring the +fact that the user hit C-c. 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. + +

  • 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. + +

  • 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. + +

  • 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 WUE 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. + +
    •  + +

    The problem

    + +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? + +

    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. + +

    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. + +

    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. + +

    Consider this script: +

    +#! /bin/sh
+emacs /tmp/foo
+cp /tmp/foo /home/user/mail/sent
+
    + +

    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. + +

    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. + +

    One more example

    + +

    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. +C-g is a normal editing key in emacs. Technically it +sends SIGINT (it was C-c, but emacs remapped the key) to +

    +
  • emacs +
  • the shell between your mailer and emacs, the one from your mailers + system("emacs /tmp/bla.44") command +
  • the mailer itself +
  • possibly another shell if your mailer was called by a shell script +or from another application using system(3) +
  • your interactive shell (which ignores it since it is interactive +and hence is not relevant to this discussion) +
    •  + +

    If everyone just exits on SIGINT, you will be left with nothing but +your login shell, without asking. + +

    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. + +

    Understand the difference: While C-g is used an a kind +of abort key in emacs, it isn't the major "abort everything" key. When +you use C-g in emacs, you want to end some internal emacs +command. You don't want your whole emacs and mailer session to end. + +

    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. + +

    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. + +

    A further look at the alternatives

    + +

    Still considering this script to examine the shell's actions in the +IUE, WUE and ICE way of handling SIGINT: +

    +#! /bin/sh
+emacs /tmp/foo
+cp /tmp/foo /home/user/mail/sent
+
    + +

    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. + +

    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. + +

    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. + +

    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. + +

    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). + +

    this still work for the normal script without SIGINT-using +programs:

    +
    +#! /bin/sh
+program1
+program2
+
    + +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. + +

    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. + +

    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. + +

    So everything is well with WCE?

    + +Well, almost. + +

    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. + +

    Unless a program messes with signal handling, the system does this +automatically. + +

    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. + +

    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. + +

    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. + +

    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. + +

    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. + +

    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. + +

    How to be a proper program

    + +

    (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.) + +

    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. + +

    But once you catch SIGINT, you have to act. + +

    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". + +

    If so, you have to tell the calling program about it by exiting +with the "I-exited-on-SIGINT" status. + +

    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. + +

    +void sigint_handler(int sig)
+{
+	
+	signal(SIGINT, SIG_DFL);
+	kill(getpid(), SIGINT);
+}
+
    + +Notes: + + + +
  • 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. + +

    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. + +

  • 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. + +

  • POSIX 1003.1 allows all these calls to appear in signal +handlers, so it is portable. + +
    •  + +

    In a bourne shell script, you can catch signals using the +trap 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. + +

    Consider this example from FreeBSD's mkdep, which is a +bourne shell script. + +

    +TMP=_mkdep$$
+trap 'rm -f $TMP ; trap 2 ; kill -2 $$' 1 2 3 13 15
+
    + +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). + +

    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. + +

    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. + +

    How to be a proper shell

    + +All this applies only for the script-executing case. Most shells will +also have interactive modes where things are different. + + + +
  • Do nothing special when SIGINT appears while you wait for a child. +You don't even have to remember that one happened. + +

  • Wait for child to exit, get the exit status. Do not truncate it +to type char. + +

  • 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". + +

  • If the latter applies, discontinue the script. + +

  • 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 + +
    +	signal(SIGINT, SIG_DFL);
+	kill(getpid(), SIGINT);
+
    + +
    •  + +

    Other remarks

    + +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. + +

    What to fight

    + +Make sure all programs really 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. + +

    Make sure people understand why you can't fake an exit-on-signal by +doing exit(...) using any numerical status. + +

    Make sure you use a shell that behaves right. Especially if you +develop programs, since it will help seeing problems. + +

    Concrete examples how to fix programs:

    +
      + +
    • The fix for FreeBSD's +time(1). 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. + +

    • Fix for FreeBSD's +truss(1). + +

    • The fix for FreeBSD's +mkdep(1), a shell script. + + +

    • Fix for FreeBSD's make(1), part 1, +part 2. + +
    + +

    Testsuite for shells

    + +I have a collection of shellscripts that test shells for the +behavior. See my download dir 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. + +

    Appendix 1 - table of implementation choices

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Method signDoes what?Example shells that implement it:What happens when a shellscript called emacs, the user used +C-g and the script has additional commands in it?What happens when a shellscript called emacs, the user did not use +C-c and the script has additional commands in it?What happens if a non-interactive child catches SIGINT?To behave properly, childs must do what?
    IUEThe shell executing a script exits immediately if it receives +SIGINT.4.4BSD ash (ash), NetBSD, FreeBSD prior to 3.0/22.8The editor session is lost and subsequent commands are not +executed.The editor continues as normal and the subsequent commands are +executed. The scripts ends immediately, returning to the caller even before +the current foreground child of the shell exits. It doesn't matter what the child does or how it exits, even if the +child continues to operate, the shell returns.
    WUEIf the shell executing a script received SIGINT while a foreground +process was running, it will exit after that child's exit.pdksh (OpenBSD /bin/sh)The editor continues as normal, but subsequent commands from the +script are not executed.The editor continues as normal and subsequent commands are +executed. The scripts returns to its caller after the current foreground +child exits, no matter how the child exited. 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.
    WCEThe 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). bash (Linux /bin/sh), most commercial /bin/sh, FreeBSD /bin/sh +from 3.0/2.2.8.The editor continues as normal and subsequent commands are +executed. The editor continues as normal and subsequent commands are +executed. 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. The child must be implemented right, or the user will not be able +to break shell scripts reliably.
    + +

    +
    ©2005 Martin Cracauer <cracauer @ cons.org> +http://www.cons.org/cracauer/ +
    Last changed: $Date: 2005/02/11 21:44:43 $ + 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 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 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 + +Then have long options defined: + + static const struct option _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 = _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", , , + +The field shall be the decimal length of the extended +header record in octets, including length string itself and the +trailing . + +[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 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 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 + 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 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 +s; all characters within the 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 |................| +... -- cgit v1.2.3