-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [...]>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ ]>
<book id="BusyBoxDocumentation">
<bookinfo>
<title>BusyBox - The Swiss Army Knife of Embedded Linux</title>
<chapter id="Syntax">
<title>How to use BusyBox</title>
- <sect1 id="How to use BusyBox">
- <title>Syntax</title
+ <sect1 id="How-to-use-BusyBox">
+ <title>Syntax</title>
<para>
<screen>
</para>
</sect1>
- <sect1 id="Invoking BusyBox">
+ <sect1 id="Invoking-BusyBox">
+ <title>Invoking BusyBox</title>
+
<para>
When you create a link to BusyBox for the function you wish to use, when
BusyBox is called using that link it will behave as if the command itself
</sect1>
- <sect1 id="Common options">
+ <sect1 id="Common-options">
+ <title>Common options</title>
+
<para>
Most BusyBox commands support the <emphasis>--help</emphasis> option to provide
a terse runtime description of their behavior.
<chapter id="Commands">
<title>BusyBox Commands</title>
- <sect1 id="Available BusyBox Commands">
+ <sect1 id="Available-BusyBox-Commands">
<title>Available BusyBox Commands</title>
<para>
Currently defined functions include:
</para>
<para>
- ar, basename, cat, chgrp, chmod, chown, chroot, chvt, clear,
- cp, cut, date, dc, dd, deallocvt, df, dirname, dmesg, du,
- dumpkmap, dutmp, echo, false, fbset, fdflush, find, free,
- freeramdisk, fsck.minix, grep, gunzip, gzip, halt, head,
- hostid, hostname, id, init, insmod, kill, killall, length, ln,
- loadacm, loadfont, loadkmap, logger, logname, ls, lsmod,
- makedevs, mkdir, mkfifo, mkfs.minix, mknod, mkswap, mktemp,
- more, mount, mt, mv, nc, nslookup, ping, poweroff, printf, ps,
- pwd, reboot, renice, rm, rmdir, rmmod, sed, setkeycodes, sh, sleep,
- sort, swapoff, swapon, sync, syslogd, tail, tar, tee, telnet,
- test, touch, tr, true, tty, umount, uname, uniq, update,
- uptime, usleep, uudecode, uuencode, wc, which, whoami, yes,
- zcat, [
+ addgroup, adduser, adjtimex, ar, basename, busybox, cat,
+ chgrp, chmod, chown, chroot, chvt, clear, cmp, cp, cpio, cut,
+ date, dc, dd, deallocvt, deluser, df, dirname, dmesg,
+ dos2unix, dpkg, dpkg-deb, du, dumpkmap, dutmp, echo, expr,
+ false, fbset, fdflush, find, free, freeramdisk, fsck.minix,
+ getopt, getty, grep, gunzip, gzip, halt, head, hostid,
+ hostname, id, ifconfig, init, insmod, kill, killall, klogd,
+ length, ln, loadacm, loadfont, loadkmap, logger, logname, ls,
+ lsmod, makedevs, md5sum, mkdir, mkfifo, mkfs.minix, mknod,
+ mkswap, mktemp, more, mount, mt, mv, nc, nslookup, ping,
+ pivot_root, poweroff, printf, ps, pwd, rdate, readlink,
+ reboot, renice, reset, rm, rmdir, rmmod, route, rpm2cpio,
+ sed, setkeycodes, sh, sleep, sort, stty, swapoff, swapon,
+ sync, syslogd, tail, tar, tee, telnet, test, tftp, touch, tr,
+ true, tty, umount, uname, uniq, unix2dos, update, uptime,
+ usleep, uudecode, uuencode, watchdog, wc, wget, which,
+ whoami, xargs, yes, zcat, [
</para>
</sect1>
</para>
</sect1>
+ <sect1 id="dos2unix">
+ <title>dos2unix</title>
+
+ <para>
+ Usage: dos2unix < dosfile > unixfile
+ </para>
+
+ <para>
+ Converts a text file from dos format to unix format.
+ </para>
+
+ </sect1>
+
+ <sect1 id="dpkg-deb">
+ <title>dpkg-deb</title>
+
+ <para>
+ Usage: dpkg-deb [OPTION] archive [directory]
+ </para>
+
+ <para>
+ Debian package archive (.deb) manipulation tool
+ </para>
+
+ <para>
+ Options:
+ </para>
+
+ <para>
+ <screen>
+ -c List the contents of the filesystem tree archive portion of the package
+ -e Extracts the control information files from a package archive into the specified directory.
+ If no directory is specified then a subdirectory DEBIAN in the current directory is used.
+ -x Silently extracts the filesystem tree from a package archive into the specified directory.
+ -X Extracts the filesystem tree from a package archive into the specified directory, listing the files as it goes.
+ If required the specified directory (but not its parents) will be created.
+ </screen>
+ <para>
+
+ <para>
+ Example:
+ </para>
+
+ <para>
+ <screen>
+ dpkg-deb -e ./busybox_0.48-1_i386.deb
+ dpkg-deb -x ./busybox_0.48-1_i386.deb ./unpack_dir
+ </screen>
+ </para>
+ </sect1>
+
<sect1 id="du">
<title>du</title>
<para>
Summarize the disk space used for each FILE or current
- directory. Disk space printed in units of 1k (i.e.
+ directory. Disk space printed in units of 1k (i.e.,
1024 bytes).
</para>
</para>
<para>
- Prints out a binary keyboard translation table to standard input.
+ Prints out a binary keyboard translation table to standard output.
+ </para>
+
+ <para>
+ Example:
+ </para>
+
+ <para>
+ <screen>
+ $ dumpkmap < keymap
+ </screen>
</para>
</sect1>
</para>
</sect1>
+ <sect1 id="expr">
+ <title>expr</title>
+
+ <para>
+ Usage: expr EXPRESSION
+ </para>
+
+ <para>
+ Prints the value of EXPRESSION to standard output.
+ </para>
+
+ <para>
+ EXPRESSION may be:
+ </para>
+
+ <para>
+ <screen>
+ ARG1 | ARG2 ARG1 if it is neither null nor 0, otherwise ARG2
+ ARG1 & ARG2 ARG1 if neither argument is null or 0, otherwise 0
+ ARG1 < ARG2 ARG1 is less than ARG2
+ ARG1 <= ARG2 ARG1 is less than or equal to ARG2
+ ARG1 = ARG2 ARG1 is equal to ARG2
+ ARG1 != ARG2 ARG1 is unequal to ARG2
+ ARG1 >= ARG2 ARG1 is greater than or equal to ARG2
+ ARG1 > ARG2 ARG1 is greater than ARG2
+ ARG1 + ARG2 arithmetic sum of ARG1 and ARG2
+ ARG1 - ARG2 arithmetic difference of ARG1 and ARG2
+ ARG1 * ARG2 arithmetic product of ARG1 and ARG2
+ ARG1 / ARG2 arithmetic quotient of ARG1 divided by ARG2
+ ARG1 % ARG2 arithmetic remainder of ARG1 divided by ARG2
+ STRING : REGEXP anchored pattern match of REGEXP in STRING
+ match STRING REGEXP same as STRING : REGEXP
+ substr STRING POS LENGTH substring of STRING, POS counted from 1
+ index STRING CHARS index in STRING where any CHARS is found, or 0
+ length STRING length of STRING
+ quote TOKEN interpret TOKEN as a string, even if it is a
+ keyword like `match' or an operator like `/'
+ ( EXPRESSION ) value of EXPRESSION
+ </screen>
+ </para>
+
+ <para>
+ Beware that many operators need to be escaped or quoted for shells.
+ Comparisons are arithmetic if both ARGs are numbers, else
+ lexicographical. Pattern matches return the string matched between
+ \( and \) or null; if \( and \) are not used, they return the number
+ of characters matched or 0.
+ </para>
+
+ </sect1>
+
+
<sect1 id="false">
<title>false</title>
<screen>
-follow Dereference symbolic links
-name PATTERN File name (leading directories removed) matches PATTERN
- -print Print the full file name followed by a newline to stdout
+ -type X Filetype matches X (where X is one of: f,d,l,b,c,...)
+ -perm PERMS Permissions match any of (+NNN); all of (-NNN); or exactly (NNN)
+ -mtime TIME Modified time is greater than (+N); less than (-N); or exactly (N) days
</screen>
</para>
</screen>
</para>
</sect1>
+
+ <sect1 id="getopt">
+ <title>getopt</title>
+
+ <para>
+ Usage: getopt [OPTIONS]...
+ </para>
+
+ <para>
+ Parse command options
+ </para>
+
+ <para>
+ <screen>
+ -a, --alternative Allow long options starting with single -\n"
+ -l, --longoptions=longopts Long options to be recognized\n"
+ -n, --name=progname The name under which errors are reported\n"
+ -o, --options=optstring Short options to be recognized\n"
+ -q, --quiet Disable error reporting by getopt(3)\n"
+ -Q, --quiet-output No normal output\n"
+ -s, --shell=shell Set shell quoting conventions\n"
+ -T, --test Test for getopt(1) version\n"
+ -u, --unqote Do not quote the output\n"
+ </screen>
+ </para>
+
+
+ <para>
+ Example:
+ </para>
+
+ <para>
+ <screen>
+ $ cat getopt.test
+ #!/bin/sh
+ GETOPT=`getopt -o ab:c:: --long a-long,b-long:,c-long:: \
+ -n 'example.busybox' -- "$@"`
+ if [ $? != 0 ] ; then exit 1 ; fi
+ eval set -- "$GETOPT"
+ while true ; do
+ case $1 in
+ -a|--a-long) echo "Option a" ; shift ;;
+ -b|--b-long) echo "Option b, argument \`$2'" ; shift 2 ;;
+ -c|--c-long)
+ case "$2" in
+ "") echo "Option c, no argument"; shift 2 ;;
+ *) echo "Option c, argument \`$2'" ; shift 2 ;;
+ esac ;;
+ --) shift ; break ;;
+ *) echo "Internal error!" ; exit 1 ;;
+ esac
+ done
+ </screen>
+ </para>
+ </sect1>
<sect1 id="grep">
<title>grep</title>
</para>
</sect1>
-< <sect1 id="gzip">
+ <sect1 id="gzip">
<title>gzip</title>
<para>
<para>
<screen>
-c Write output to standard output
+ -d decompress
</screen>
</para>
<para>
<screen>
- -s Short
- -i Addresses for the hostname
- -d DNS domain name
- -F FILE Use the contents of FILE to specify the hostname
+ -s Short
+ -i Addresses for the hostname
+ -d DNS domain name
+ -F, --file FILE Use the contents of FILE to specify the hostname
</screen>
</para>
<screen>
-g Print only the group ID
-u Print only the user ID
+ -n print a name instead of a number (with for -ug)
-r Print the real user ID instead of the effective ID (with -ug)
</screen>
</para>
<screen>
<id>:<runlevels>:<action>:<process>
</screen>
- <para>
+ </para>
<sect2>
<title>id</title>
<para>
- WARNING: This field has a non-traditional
- meaning for BusyBox init! The id field is used
- by BusyBox init to specify the controlling tty
- for the specified process to run on. The
- contents of this field are appended to "/dev/"
- and used as-is. There is no need for this field
- to be unique, although if it isn't you may have
- strange results. If this field is left blank,
- it is completely ignored. Also note that if
- BusyBox detects that a serial console is in use,
- then all entries containing non-empty id fields
- will _not_ be run. BusyBox init does nothing
- with utmp. We don't need no stinkin' utmp.
+
+ WARNING: This field has a non-traditional meaning for BusyBox init!
+ The id field is used by BusyBox init to specify the controlling tty
+ for the specified process to run on. The contents of this field
+ are appended to "/dev/" and used as-is. There is no need for this
+ field to be unique, although if it isn't you may have strange
+ results. If this field is left blank, the controlling tty is set
+ to the console. Also note that if BusyBox detects that a serial
+ console is in use, then only entries whose controlling tty is
+ either the serial console or /dev/null will be run. BusyBox init
+ does nothing with utmp. We don't need no stinkin' utmp.
+
</para>
</sect2>
<sect2>
<title>action</title>
+
+ <para>
+ Valid actions include: sysinit, respawn, askfirst, wait,
+ once, and ctrlaltdel.
+ </para>
+
+
+ <para>
+ The available actions can be classified into two groups: actions
+ that are run only once, and actions that are re-run when the specified
+ process exits.
+ </para>
+
+ <para>
+ Run only-once actions:
+ </para>
+
<para>
- Valid actions include: sysinit, respawn,
- askfirst, wait, once, and ctrlaltdel.
+ 'sysinit' is the first item run on boot. init waits until all
+ sysinit actions are completed before continuing. Following the
+ completion of all sysinit actions, all 'wait' actions are run.
+ 'wait' actions, like 'sysinit' actions, cause init to wait until
+ the specified task completes. 'once' actions are asyncronous,
+ therefore, init does not wait for them to complete. 'ctrlaltdel'
+ actions are run immediately before init causes the system to reboot
+ (unmounting filesystems with a 'ctrlaltdel' action is a very good
+ idea).
</para>
<para>
- askfirst acts just like respawn, but before
- running the specified process it displays the
- line "Please press Enter to activate this
- console." and then waits for the user to press
- enter before starting the specified process.
+ Run repeatedly actions:
</para>
<para>
- Unrecognized actions (like initdefault) will
- cause init to emit an error message, and then go
- along with its business.
+ 'respawn' actions are run after the 'once' actions. When a process
+ started with a 'respawn' action exits, init automatically restarts
+ it. Unlike sysvinit, BusyBox init does not stop processes from
+ respawning out of control. The 'askfirst' actions acts just like
+ respawn, except that before running the specified process it
+ displays the line "Please press Enter to activate this console."
+ and then waits for the user to press enter before starting the
+ specified process.
</para>
+
+ <para>
+ Unrecognized actions (like initdefault) will cause init to emit an
+ error message, and then go along with its business. All actions are
+ run in the reverse order from how they appear in /etc/inittab.
+ </para>
+
</sect2>
<sect2>
</para>
</sect2>
- <para>
- Example /etc/inittab file:
- </para>
-
- <para>
- <screen>
- # This is run first except when booting in single-user mode.
- #
- ::sysinit:/etc/init.d/rcS
-
- # /bin/sh invocations on selected ttys
- #
- # Start an "askfirst" shell on the console (whatever that may be)
- ::askfirst:/bin/sh
- # Start an "askfirst" shell on /dev/tty2
- tty2::askfirst:/bin/sh
-
- # /sbin/getty invocations for selected ttys
- #
- tty4::respawn:/sbin/getty 38400 tty4
- tty5::respawn:/sbin/getty 38400 tty5
-
- # Example of how to put a getty on a serial line (for a terminal)
- #
- #ttyS0::respawn:/sbin/getty -L ttyS0 9600 vt100
- #ttyS1::respawn:/sbin/getty -L ttyS1 9600 vt100
- #
- # Example how to put a getty on a modem line.
- #ttyS2::respawn:/sbin/getty -x0 -s 57600 ttyS2
-
- # Stuff to do before rebooting
- ::ctrlaltdel:/bin/umount -a -r > /dev/null 2>&1
- ::ctrlaltdel:/sbin/swapoff -a > /dev/null 2>&1
- </screen>
- </para>
+ <sect2>
+ <title>Example /etc/inittab file</title>
+
+ <para>
+ <screen>
+ # This is run first except when booting in single-user mode.
+ #
+ ::sysinit:/etc/init.d/rcS
+
+ # /bin/sh invocations on selected ttys
+ #
+ # Start an "askfirst" shell on the console (whatever that may be)
+ ::askfirst:-/bin/sh
+ # Start an "askfirst" shell on /dev/tty2-4
+ tty2::askfirst:-/bin/sh
+ tty2::askfirst:-/bin/sh
+ tty2::askfirst:-/bin/sh
+
+ # /sbin/getty invocations for selected ttys
+ #
+ tty4::respawn:/sbin/getty 38400 tty5
+ tty5::respawn:/sbin/getty 38400 tty6
+
+ # Example of how to put a getty on a serial line (for a terminal)
+ #
+ #::respawn:/sbin/getty -L ttyS0 9600 vt100
+ #::respawn:/sbin/getty -L ttyS1 9600 vt100
+ #
+ # Example how to put a getty on a modem line.
+ #::respawn:/sbin/getty 57600 ttyS2
+
+ # Stuff to do before rebooting
+ ::ctrlaltdel:/bin/umount -a -r
+ ::ctrlaltdel:/sbin/swapoff
+ </screen>
+ </para>
+ </sect2>
</sect1>
<sect1 id="insmod">
-k Make module autoclean-able.
-v Verbose output
-x Do not export externs
+ -L Prevent simultaneous loads of the same module
</screen>
</para>
</sect1>
</para>
<para>
- Write MESSAGE to the system log. If MESSAGE is '-', log
+ Write MESSAGE to the system log. If MESSAGE is omitted, log
stdin.
</para>
-A Do not list implied . and ..
-C List entries by columns
-F Append indicator (one of */=@|) to entries
+ -L list entries pointed to by symbolic links
-R List subdirectories recursively
</screen>
</para>
<para>
Creates a temporary file with its name based on
- TEMPLATE. TEMPLATE is any name with six `Xs' (i.e.
+ TEMPLATE. TEMPLATE is any name with six `Xs' (i.e.,
/tmp/temp.XXXXXX).
</para>
</para>
<para>
- Open a pipe to HOST:PORT.
+ or: nc -p PORT -l
+ </para>
+
+
+ <para>
+ Open a pipe to HOST:PORT or listen for a connection on PORT.
</para>
<para>
</para>
</sect1>
+ <sect1 id="rdate">
+ <title>rdate</title>
+
+ <para>
+ Usage: rdate [OPTION] HOST
+ </para>
+
+ <para>
+ Get and possibly set the system date and time from a remote HOST.
+ </para>
+
+ <para>
+ Options:
+ </para>
+
+ <para>
+ <screen>
+ -s Set the system date and time (default).
+ -p Print the date and time.
+ </screen>
+ </para>
+ </sect1>
+
<sect1 id="reboot">
<title>reboot</title>
</para>
</sect1>
+ <sect1 id="reset">
+ <title>reset</title>
+
+ <para>
+ Usage: reset
+ </para>
+
+ <para>
+ Resets the screen.
+ </para>
+ </sect1>
+
<sect1 id="rm">
<title>rm</title>
<para>
<screen>
+ -i Always prompt before removing each destinations
-f Remove existing destinations, never prompt
-r or -R Remove the contents of directories recursively
</screen>
</para>
</sect1>
+ <sect1 id="run-parts">
+ <title>run-parts</title>
+
+ <para>
+ Usage: run-parts [-t] [-a ARG] [-u MASK] DIRECTORY
+ </para>
+
+ <para>
+ Run a bunch of scripts in a directory.
+ </para>
+
+ <para>
+ Options:
+ </para>
+
+ <para>
+ <screen>
+ -t Test only. It only print the file to be executed,
+ without execute them.
+ -a ARG Pass ARG as an a argument to the programs executed.
+ -u MASK Set the umask to MASK before executing the programs.
+ </screen>
+ </para>
+ </sect1>
+
+
+
<sect1 id="sed">
<title>sed</title>
-n Run as a foreground process
-K Do not start up the klogd process
-O FILE Use an alternate log file (default=/var/log/messages)
- -R HOST[:PORT] Log messages to HOST on PORT (default=514) over UDP.
+ -R HOST[:PORT] Log remotely to IP or hostname on PORT (default PORT=514/UDP)
+ -L Log locally as well as network logging (default is network only)
+ -C Log to a circular buffer. Read this buffer using 'logread'
</screen>
</para>
<para>
<screen>
- f FILE Use FILE for tarfile (or stdin if '-')
- O Extract to stdout
- --exclude FILE Exclude FILE
- v List files processed
+ f FILE Use FILE for tarfile (or stdin if '-')
+ O Extract to stdout
+ exclude FILE File to exclude
+ v List files processed
</screen>
</para>
</para>
<para>
- <screen>
or: [ EXPRESSION ]
+ </para>
<para>
Check file types and compare values returning an exit
<screen>
-a Unmount all file systems
-r Try to remount devices as read-only if mount is busy
- -f Force filesystem umount (i.e. unreachable NFS server)
+ -f Force filesystem umount (i.e., unreachable NFS server)
-l Do not free loop device (if a loop device has been used)
</screen>
</para>
INPUT (or stdin), writing to OUTPUT (or stdout).
</para>
+ <para>
+ Options:
+ </para>
+
+ <para>
+ <screen>
+ -c prefix lines by the number of occurrences
+ -d only print duplicate lines
+ -u only print unique lines
+ </screen>
+ </para>
+
<para>
Example:
</para>
</screen>
</para>
</sect1>
+
+ <sect1 id="unix2dos">
+ <title>unix2dos</title>
+
+ <para>
+ Usage: unix2dos < unixfile > dosfile
+ </para>
+
+ <para>
+ Converts a text file from unix format to dos format.
+ </para>
+
+ </sect1>
+
+ <sect1 id="unrpm">
+ <title>unrpm</title>
+
+ <para>
+ Usage: unrpm < package.rpm | gzip -d | cpio -idmuv
+ </para>
+
+ <para>
+ Extracts an rpm archive.
+ </para>
+
+ </sect1>
<sect1 id="update">
<title>update</title>
</para>
</sect1>
+ <sect1 id="watchdog">
+ <title>watchdog</title>
+
+ <para>
+ Usage: watchdog device
+ </para>
+
+ <para>
+ Periodically writes to watchdog device B<device>.
+ </para>
+ </sect1>
+
<sect1 id="wc">
<title>wc</title>
</para>
</sect1>
+ <sect1 id="xargs">
+ <title>xargs</title>
+
+ <para>
+ Usage: xargs [OPTIONS] [COMMAND] [ARGS...]
+ </para>
+
+ <para>
+ Executes COMMAND on every item given by standard input.
+ </para>
+
+ <para>
+ Options:
+ </para>
+
+ <para>
+ <screen>
+ -t Print the command just before it is run
+ </screen>
+ </para>
+
+
+ <para>
+ Example:
+ </para>
+
+ <para>
+ <screen>
+ $ ls | xargs gzip
+ $ find . -name '*.c' -print | xargs rm
+ </screen>
+ </para>
+ </sect1>
+
<sect1 id="yes">
<title>yes</title>
<title>AUTHORS</title>
<para>
- The following people have contributed code to BusyBox whether
- they know it or not.
+ The following people have made significant contributions to
+ BusyBox -- whether they know it or not.
</para>
<para>
Erik Andersen <andersee@debian.org>
</para>
+ <para>
+ Edward Betts <edward@debian.org>
+ </para>
+
<para>
John Beppu <beppu@lineo.com>
</para>
Karl M. Hegbloom <karlheg@debian.org>
</para>
+ <para>
+ Daniel Jacobowitz <dan@debian.org>
+ </para>
+
+ <para>
+ Matt Kraai <kraai@alumni.carnegiemellon.edu>
+ </para>
+
<para>
John Lombardo <john@deltanet.com>
</para>
Bruce Perens <bruce@perens.com>
</para>
+ <para>
+ Chip Rosenthal <chip@unicom.com>, <crosenth@covad.com>
+ </para>
+
<para>
Pavel Roskin <proski@gnu.org>
</para>
+ <para>
+ Gyepi Sam <gyepi@praxis-sw.com>
+ </para>
+
<para>
Linus Torvalds <torvalds@transmeta.com>
</para>
+ <para>
+ Mark Whitley <markw@lineo.com>
+ </para>
+
<para>
Charles P. Wright <cpwright@villagenet.com>
</para>
<para>
Enrique Zanardi <ezanardi@ull.es>
</para>
+
+ <para>
+ Vladimir Oleynik <dzo@simtreas.ru>
+ </para>
+
+
</chapter>
</book> <!-- End of the book -->