devel/coreutils/coreutils-pam.patch

diff -urNp coreutils-8.0-orig/configure.ac coreutils-8.0/configure.ac
--- coreutils-8.0-orig/configure.ac	2009-09-29 15:27:11.000000000 +0200
+++ coreutils-8.0/configure.ac	2009-10-07 10:04:27.000000000 +0200
@@ -115,6 +115,13 @@ if test "$gl_gcc_warnings" = yes; then
   AC_DEFINE([GNULIB_PORTCHECK], [1], [enable some gnulib portability checks])
 fi
 
+dnl Give the chance to enable PAM
+AC_ARG_ENABLE(pam, dnl
+[  --enable-pam              Enable use of the PAM libraries],
+[AC_DEFINE(USE_PAM, 1, [Define if you want to use PAM])
+LIB_PAM="-ldl -lpam -lpam_misc"
+AC_SUBST(LIB_PAM)])
+
 AC_FUNC_FORK
 
 optional_bin_progs=
diff -urNp coreutils-8.0-orig/configure.ac.orig coreutils-8.0/configure.ac.orig
--- coreutils-8.0-orig/configure.ac.orig	1970-01-01 01:00:00.000000000 +0100
+++ coreutils-8.0/configure.ac.orig	2009-09-29 15:27:11.000000000 +0200
@@ -0,0 +1,439 @@
+# -*- autoconf -*-
+# Process this file with autoconf to produce a configure script.
+
+# Copyright (C) 1991, 1993-2009 Free Software Foundation, Inc.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+dnl Written by Jim Meyering.
+
+AC_PREREQ([2.61])
+
+# Make inter-release version strings look like, e.g., v6.9-219-g58ddd, which
+# indicates that it is built from the 219th delta (in _some_ repository)
+# following the v6.9 tag, and that 58ddd is a prefix of the commit SHA1.
+AC_INIT([GNU coreutils],
+        m4_esyscmd([build-aux/git-version-gen .tarball-version]),
+        [bug-coreutils@gnu.org])
+
+AC_CONFIG_SRCDIR([src/ls.c])
+
+AC_CONFIG_AUX_DIR([build-aux])
+AC_CONFIG_HEADERS([lib/config.h:lib/config.hin])
+
+AM_INIT_AUTOMAKE([1.11 dist-xz color-tests parallel-tests])
+AM_SILENT_RULES([yes]) # make --enable-silent-rules the default.
+
+AC_PROG_CC_STDC
+AM_PROG_CC_C_O
+AC_PROG_CPP
+AC_PROG_GCC_TRADITIONAL
+AC_PROG_RANLIB
+AC_PROG_LN_S
+gl_EARLY
+gl_INIT
+coreutils_MACROS
+
+AC_ARG_ENABLE([gcc-warnings],
+  [AS_HELP_STRING([--enable-gcc-warnings],
+                  [turn on lots of GCC warnings (for developers)])],
+  [case $enableval in
+     yes|no) ;;
+     *)      AC_MSG_ERROR([bad value $enableval for gcc-warnings option]) ;;
+   esac
+   gl_gcc_warnings=$enableval],
+  [gl_gcc_warnings=no]
+)
+
+if test "$gl_gcc_warnings" = yes; then
+  gl_WARN_ADD([-Werror], [WERROR_CFLAGS])
+  AC_SUBST([WERROR_CFLAGS])
+
+  nw=
+  # This, $nw, is the list of warnings we disable.
+  nw="$nw -Wdeclaration-after-statement" # too useful to forbid
+  nw="$nw -Waggregate-return"       # anachronistic
+  nw="$nw -Wlong-long"              # C90 is anachronistic (lib/gethrxtime.h)
+  nw="$nw -Wc++-compat"             # We don't care about C++ compilers
+  nw="$nw -Wundef"                  # Warns on '#if GNULIB_FOO' etc in gnulib
+  nw="$nw -Wtraditional"            # Warns on #elif which we use often
+  nw="$nw -Wcast-qual"              # Too many warnings for now
+  nw="$nw -Wconversion"             # Too many warnings for now
+  nw="$nw -Wsystem-headers"         # Don't let system headers trigger warnings
+  nw="$nw -Wsign-conversion"        # Too many warnings for now
+  nw="$nw -Wtraditional-conversion" # Too many warnings for now
+  nw="$nw -Wunreachable-code"       # Too many warnings for now
+  nw="$nw -Wpadded"                 # Our structs are not padded
+  nw="$nw -Wredundant-decls"        # openat.h declares e.g., mkdirat
+  nw="$nw -Wlogical-op"             # any use of fwrite provokes this
+  nw="$nw -Wformat-nonliteral"      # who.c and pinky.c strftime uses
+  nw="$nw -Wvla"                    # warnings in gettext.h
+  nw="$nw -Wnested-externs"         # use of XARGMATCH/verify_function__
+  nw="$nw -Wswitch-enum"            # Too many warnings for now
+  nw="$nw -Wswitch-default"         # Too many warnings for now
+  nw="$nw -Wstack-protector"        # not worth working around
+  # things I might fix soon:
+  nw="$nw -Wfloat-equal"            # sort.c, seq.c
+  nw="$nw -Wmissing-format-attribute" # copy.c
+  nw="$nw -Wunsafe-loop-optimizations" # a few src/*.c
+  nw="$nw -Winline"                 # system.h's readdir_ignoring_dot_and_dotdot
+  nw="$nw -Wstrict-overflow"        # expr.c, pr.c, tr.c, factor.c
+  # ?? -Wstrict-overflow
+
+  gl_MANYWARN_ALL_GCC([ws])
+  gl_MANYWARN_COMPLEMENT([ws], [$ws], [$nw])
+  for w in $ws; do
+    gl_WARN_ADD([$w])
+  done
+  gl_WARN_ADD([-Wno-missing-field-initializers]) # We need this one
+  gl_WARN_ADD([-Wno-sign-compare])     # Too many warnings for now
+  gl_WARN_ADD([-Wno-pointer-sign])     # Too many warnings for now
+  gl_WARN_ADD([-Wno-unused-parameter]) # Too many warnings for now
+
+  # In spite of excluding -Wlogical-op above, it is enabled, as of
+  # gcc 4.5.0 20090517, and it provokes warnings in cat.c, dd.c, truncate.c
+  gl_WARN_ADD([-Wno-logical-op])
+
+  gl_WARN_ADD([-fdiagnostics-show-option])
+
+  AC_SUBST([WARN_CFLAGS])
+
+  AC_DEFINE([lint], [1], [Define to 1 if the compiler is checking for lint.])
+  AC_DEFINE([_FORTIFY_SOURCE], [2],
+    [enable compile-time and run-time bounds-checking, and some warnings])
+  AC_DEFINE([GNULIB_PORTCHECK], [1], [enable some gnulib portability checks])
+fi
+
+AC_FUNC_FORK
+
+optional_bin_progs=
+AC_CHECK_FUNCS([uname],
+        gl_ADD_PROG([optional_bin_progs], [uname]))
+AC_CHECK_FUNCS([chroot],
+        gl_ADD_PROG([optional_bin_progs], [chroot]))
+AC_CHECK_FUNCS([gethostid],
+        gl_ADD_PROG([optional_bin_progs], [hostid]))
+
+gl_WINSIZE_IN_PTEM
+
+AC_MSG_CHECKING([whether localtime caches TZ])
+AC_CACHE_VAL([utils_cv_localtime_cache],
+[if test x$ac_cv_func_tzset = xyes; then
+AC_RUN_IFELSE([AC_LANG_SOURCE([[#include <time.h>
+#if STDC_HEADERS
+# include <stdlib.h>
+#endif
+extern char **environ;
+void unset_TZ (void)
+{
+  char **from, **to;
+  for (to = from = environ; (*to = *from); from++)
+    if (! (to[0][0] == 'T' && to[0][1] == 'Z' && to[0][2] == '='))
+      to++;
+}
+int main()
+{
+  time_t now = time ((time_t *) 0);
+  int hour_GMT0, hour_unset;
+  if (putenv ("TZ=GMT0") != 0)
+    exit (1);
+  hour_GMT0 = localtime (&now)->tm_hour;
+  unset_TZ ();
+  hour_unset = localtime (&now)->tm_hour;
+  if (putenv ("TZ=PST8") != 0)
+    exit (1);
+  if (localtime (&now)->tm_hour == hour_GMT0)
+    exit (1);
+  unset_TZ ();
+  if (localtime (&now)->tm_hour != hour_unset)
+    exit (1);
+  exit (0);
+}]])],
+[utils_cv_localtime_cache=no],
+[utils_cv_localtime_cache=yes],
+[# If we have tzset, assume the worst when cross-compiling.
+utils_cv_localtime_cache=yes])
+else
+        # If we lack tzset, report that localtime does not cache TZ,
+        # since we can't invalidate the cache if we don't have tzset.
+        utils_cv_localtime_cache=no
+fi])dnl
+AC_MSG_RESULT([$utils_cv_localtime_cache])
+if test $utils_cv_localtime_cache = yes; then
+  AC_DEFINE([LOCALTIME_CACHE], [1], [FIXME])
+fi
+
+# SCO-ODT-3.0 is reported to need -los to link programs using initgroups
+AC_CHECK_FUNCS([initgroups])
+if test $ac_cv_func_initgroups = no; then
+  AC_CHECK_LIB([os], [initgroups])
+fi
+
+AC_CHECK_FUNCS([syslog])
+if test $ac_cv_func_syslog = no; then
+  # syslog is not in the default libraries.  See if it's in some other.
+  for lib in bsd socket inet; do
+    AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG], [1], [FIXME])
+      LIBS="$LIBS -l$lib"; break])
+  done
+fi
+
+AC_CACHE_CHECK([for 3-argument setpriority function],
+  [utils_cv_func_setpriority],
+  [AC_LINK_IFELSE(
+    [AC_LANG_PROGRAM(
+       [[#include <sys/time.h>
+         #include <sys/resource.h>
+       ]],
+       [[setpriority (0, 0, 0);]])],
+    [utils_cv_func_setpriority=yes],
+    [utils_cv_func_setpriority=no])])
+if test $utils_cv_func_setpriority = no; then
+  AC_CHECK_FUNCS([nice])
+fi
+case $utils_cv_func_setpriority,$ac_cv_func_nice in
+*yes*)
+  gl_ADD_PROG([optional_bin_progs], [nice])
+esac
+
+AC_DEFUN([coreutils_DUMMY_1],
+[
+  AC_REQUIRE([gl_READUTMP])
+  if test $ac_cv_header_utmp_h = yes || test $ac_cv_header_utmpx_h = yes; then
+    gl_ADD_PROG([optional_bin_progs], [who])
+    gl_ADD_PROG([optional_bin_progs], [users])
+    gl_ADD_PROG([optional_bin_progs], [pinky])
+  fi
+])
+coreutils_DUMMY_1
+
+AC_MSG_CHECKING([ut_host in struct utmp])
+AC_CACHE_VAL([su_cv_func_ut_host_in_utmp],
+[AC_LINK_IFELSE([AC_LANG_PROGRAM([[#include <sys/types.h>
+#include <utmp.h>]], [[struct utmp ut; return !sizeof ut.ut_host;]])],
+  [su_cv_func_ut_host_in_utmp=yes],
+  [su_cv_func_ut_host_in_utmp=no])])
+AC_MSG_RESULT([$su_cv_func_ut_host_in_utmp])
+if test $su_cv_func_ut_host_in_utmp = yes; then
+  have_ut_host=1
+  AC_DEFINE([HAVE_UT_HOST], [1], [FIXME])
+fi
+
+if test -z "$have_ut_host"; then
+  AC_MSG_CHECKING([ut_host in struct utmpx])
+  AC_CACHE_VAL([su_cv_func_ut_host_in_utmpx],
+  [AC_LINK_IFELSE([AC_LANG_PROGRAM([[#include <sys/types.h>
+#include <utmpx.h>]], [[struct utmpx ut; return !sizeof ut.ut_host;]])],
+    [su_cv_func_ut_host_in_utmpx=yes],
+    [su_cv_func_ut_host_in_utmpx=no])])
+  AC_MSG_RESULT([$su_cv_func_ut_host_in_utmpx])
+  if test $su_cv_func_ut_host_in_utmpx = yes; then
+    AC_DEFINE([HAVE_UTMPX_H], [1], [FIXME])
+    AC_DEFINE([HAVE_UT_HOST], [1], [FIXME])
+  fi
+fi
+
+GNULIB_BOOT_TIME([gl_ADD_PROG([optional_bin_progs], [uptime])])
+
+AC_SYS_POSIX_TERMIOS()
+gl_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
+
+if test $ac_cv_sys_posix_termios = yes; then
+  gl_ADD_PROG([optional_bin_progs], [stty])
+
+  AC_MSG_CHECKING([whether termios.h needs _XOPEN_SOURCE])
+  AC_CACHE_VAL([su_cv_sys_termios_needs_xopen_source],
+  [AC_EGREP_CPP([yes], [#include <termios.h>
+#ifdef IUCLC
+yes
+#endif], su_cv_sys_termios_needs_xopen_source=no,
+   AC_EGREP_CPP([yes], [#define _XOPEN_SOURCE
+#include <termios.h>
+#ifdef IUCLC
+yes
+#endif], su_cv_sys_termios_needs_xopen_source=yes,
+   su_cv_sys_termios_needs_xopen_source=no))])
+  AC_MSG_RESULT([$su_cv_sys_termios_needs_xopen_source])
+  test $su_cv_sys_termios_needs_xopen_source = yes &&
+    AC_DEFINE([TERMIOS_NEEDS_XOPEN_SOURCE], [1], [FIXME])
+
+  AC_MSG_CHECKING([c_line in struct termios])
+  AC_CACHE_VAL([su_cv_sys_c_line_in_termios],
+  [AC_LINK_IFELSE([AC_LANG_PROGRAM([[#if TERMIOS_NEEDS_XOPEN_SOURCE
+#define _XOPEN_SOURCE
+#endif
+#include <sys/types.h>
+#include <termios.h>]], [[struct termios t; return !sizeof t.c_line;]])],
+    [su_cv_sys_c_line_in_termios=yes],
+    [su_cv_sys_c_line_in_termios=no])])
+  AC_MSG_RESULT([$su_cv_sys_c_line_in_termios])
+  test $su_cv_sys_c_line_in_termios = yes \
+    && AC_DEFINE([HAVE_C_LINE], [1], [FIXME])
+fi
+
+# FIXME: note that this macro appears above, too.
+# I'm leaving it here for now.  This whole thing needs to be modernized...
+gl_WINSIZE_IN_PTEM
+
+gl_HEADER_TIOCGWINSZ_IN_TERMIOS_H
+
+if test $gl_cv_sys_tiocgwinsz_needs_termios_h = no && \
+   test $gl_cv_sys_tiocgwinsz_needs_sys_ioctl_h = no; then
+  AC_MSG_CHECKING([TIOCGWINSZ in sys/pty.h])
+  AC_CACHE_VAL([su_cv_sys_tiocgwinsz_in_sys_pty_h],
+  [AC_LINK_IFELSE([AC_LANG_PROGRAM([[#include <sys/types.h>
+#ifdef WINSIZE_IN_PTEM
+# include <sys/stream.h>
+# include <sys/ptem.h>
+#endif
+#include <sys/ioctl.h>
+#include <sys/tty.h>
+#include <sys/pty.h>]], [[int x = TIOCGWINSZ;]])],
+    [su_cv_sys_tiocgwinsz_in_sys_pty_h=yes],
+    [su_cv_sys_tiocgwinsz_in_sys_pty_h=no])])
+  AC_MSG_RESULT([$su_cv_sys_tiocgwinsz_in_sys_pty_h])
+
+  test $su_cv_sys_tiocgwinsz_in_sys_pty_h = yes \
+      && AC_DEFINE([GWINSZ_IN_SYS_PTY], [1],
+                   [Define if your system defines TIOCGWINSZ in sys/pty.h.])
+fi
+
+# For src/kill.c.
+AC_CHECK_DECLS([strsignal, sys_siglist, _sys_siglist, __sys_siglist], , ,
+  [AC_INCLUDES_DEFAULT
+#include <signal.h>])
+
+cu_LIB_CHECK
+cu_GMP
+
+# Build df only if there's a point to it.
+if test $gl_cv_list_mounted_fs = yes && test $gl_cv_fs_space = yes; then
+  gl_ADD_PROG([optional_bin_progs], [df])
+fi
+
+# Limit stdbuf to ELF systems with GCC
+optional_pkglib_progs=
+AC_MSG_CHECKING([whether this is an ELF system])
+AC_EGREP_CPP([yes], [#if __ELF__
+yes
+#endif], [elf_sys=yes], [elf_sys=no])
+AC_MSG_RESULT([$elf_sys])
+if test "$elf_sys" = "yes" && \
+   test "$GCC" = "yes"; then
+  gl_ADD_PROG([optional_bin_progs], [stdbuf])
+  gl_ADD_PROG([optional_pkglib_progs], [libstdbuf.so])
+fi
+
+############################################################################
+mk="$srcdir/src/Makefile.am"
+# Extract all literal names from the definition of $(EXTRA_PROGRAMS)
+# in $mk but don't expand the variable references.
+# Append each literal name to $optional_bin_progs.
+v=EXTRA_PROGRAMS
+for gl_i in `sed -n '/^'$v' =/,/[[^\]]$/p' $mk \
+    | sed 's/^  *//;/^\$.*/d;/^'$v' =/d' \
+    | tr -s '\\015\\012\\\\' '   '`; do
+  gl_ADD_PROG([optional_bin_progs], $gl_i)
+done
+
+# As above, extract literal names from the definition of $(no_install__progs)
+# in $mk but don't expand the variable references.
+v=no_install__progs
+t=`sed -n '/^'$v' =/,/[[^\]]$/p' $mk \
+    | sed 's/^  *//;/^\$.*/d;/^'$v' =/d' \
+    | tr -s '\\015\\012\\\\' '   '`
+# Remove any trailing space.
+no_install_progs_default=`echo "$t"|sed 's/ $//'`
+
+# Unfortunately, due to the way autoconf's AS_HELP_STRING works, the list
+# of default-not-installed programs, "arch hostname su", must appear in two
+# places: in this file below, and in $mk.  Using "$no_install_progs_default"
+# below cannot work.  And we can't substitute the names into $mk because
+# automake needs the literals, too.
+# The compromise is to ensure that the space-separated list extracted
+# above matches the literal 2nd argument below.
+c="$srcdir/configure.ac"
+re='^g''l_INCLUDE_EXCLUDE_PROG(.* [\[\(.*\)\]])'
+t=`sed -n '/'"$re"'/{s/'"$re"'/\1/;s/,/ /gp
+}' $c`
+case $t in
+  $no_install_progs_default) ;;
+  *) AC_MSG_ERROR([[internal error: g'l_INCLUDE_EXCLUDE_PROG's 2nd arg, $t,
+                   does not match the list of default-not-installed programs
+                   ($no_install_progs_default) also recorded in $mk]],
+                   1) ;;
+esac
+
+# Given the name of a variable containing a space-separated list of
+# install-by-default programs and the actual list do-not-install-by-default
+# programs, modify the former variable to reflect any "do-install" and
+# "don't-install" requests.
+# I.e., add any program name specified via --enable-install-program=..., and
+# remove any program name specified via --enable-no-install-program=...
+# Note how the second argument below is a literal, with "," separators.
+# That is required due to the way the macro works, and since the
+# corresponding ./configure option argument is comma-separated on input.
+gl_INCLUDE_EXCLUDE_PROG([optional_bin_progs], [arch,hostname,su])
+
+# Set INSTALL_SU if su installation has been requested via
+# --enable-install-program=su.
+AC_SUBST([INSTALL_SU])
+case " $optional_bin_progs " in
+  *' su '*) INSTALL_SU=yes ;;
+  *)        INSTALL_SU=no ;;
+esac
+
+MAN=`echo "$optional_bin_progs "|sed 's/ /.1 /g;s/ $//'|tr -d '\\015\\012'`
+
+# Change ginstall.1 to "install.h" in $MAN.
+MAN=`for m in $MAN; do test $m = ginstall.1 && m=install.1; echo $m; done \
+  | tr '\015\012' '  '; echo`
+
+# Remove [.1, since writing a portable rule for it in man/Makefile.am
+# is not practical.  The sed LHS below uses the autoconf quadrigraph
+# representing '['.
+MAN=`echo "$MAN"|sed 's/\@<:@\.1//'`
+
+OPTIONAL_BIN_PROGS=`echo "$optional_bin_progs "|sed 's/ /\$(EXEEXT) /g;s/ $//'`
+AC_SUBST([OPTIONAL_BIN_PROGS])
+OPTIONAL_PKGLIB_PROGS=`echo "$optional_pkglib_progs " | sed 's/ $//'`
+AC_SUBST([OPTIONAL_PKGLIB_PROGS])
+NO_INSTALL_PROGS_DEFAULT=$no_install_progs_default
+AC_SUBST([NO_INSTALL_PROGS_DEFAULT])
+
+AM_CONDITIONAL([CROSS_COMPILING], [test "$cross_compiling" = yes])
+
+# Arrange to rerun configure whenever the file, src/Makefile.am,
+# containing the list of program names changes.
+CONFIG_STATUS_DEPENDENCIES='$(top_srcdir)/src/Makefile.am'
+AC_SUBST([CONFIG_STATUS_DEPENDENCIES])
+############################################################################
+
+AM_GNU_GETTEXT([external], [need-formatstring-macros])
+AM_GNU_GETTEXT_VERSION([0.15])
+
+# For a test of uniq: it uses the $LOCALE_FR envvar.
+gt_LOCALE_FR
+
+AC_CONFIG_FILES(
+  Makefile
+  doc/Makefile
+  lib/Makefile
+  man/Makefile
+  po/Makefile.in
+  src/Makefile
+  tests/Makefile
+  gnulib-tests/Makefile
+  )
+AC_OUTPUT
diff -urNp coreutils-8.0-orig/doc/coreutils.texi coreutils-8.0/doc/coreutils.texi
--- coreutils-8.0-orig/doc/coreutils.texi	2009-09-29 15:27:54.000000000 +0200
+++ coreutils-8.0/doc/coreutils.texi	2009-10-07 10:04:27.000000000 +0200
@@ -14742,8 +14742,11 @@ to certain shells, etc.).
 @findex syslog
 @command{su} can optionally be compiled to use @code{syslog} to report
 failed, and optionally successful, @command{su} attempts.  (If the system
-supports @code{syslog}.)  However, GNU @command{su} does not check if the
-user is a member of the @code{wheel} group; see below.
+supports @code{syslog}.)
+
+This version of @command{su} has support for using PAM for
+authentication.  You can edit @file{/etc/pam.d/su} to customize its
+behaviour.
 
 The program accepts the following options.  Also see @ref{Common options}.
 
@@ -14785,6 +14788,8 @@ environment variables except @env{TERM},
 @env{PATH} to a compiled-in default value.  Change to @var{user}'s home
 directory.  Prepend @samp{-} to the shell's name, intended to make it
 read its login startup file(s).
+Additionaly @env{DISPLAY} and @env{XAUTHORITY} environment variables 
+are preserved as well for PAM functionality.
 
 @item -m
 @itemx -p
@@ -14824,33 +14829,6 @@ Exit status:
 the exit status of the subshell otherwise
 @end display
 
-@cindex wheel group, not supported
-@cindex group wheel, not supported
-@cindex fascism
-@subsection Why GNU @command{su} does not support the @samp{wheel} group
-
-(This section is by Richard Stallman.)
-
-@cindex Twenex
-@cindex MIT AI lab
-Sometimes a few of the users try to hold total power over all the
-rest.  For example, in 1984, a few users at the MIT AI lab decided to
-seize power by changing the operator password on the Twenex system and
-keeping it secret from everyone else.  (I was able to thwart this coup
-and give power back to the users by patching the kernel, but I
-wouldn't know how to do that in Unix.)
-
-However, occasionally the rulers do tell someone.  Under the usual
-@command{su} mechanism, once someone learns the root password who
-sympathizes with the ordinary users, he or she can tell the rest.  The
-``wheel group'' feature would make this impossible, and thus cement the
-power of the rulers.
-
-I'm on the side of the masses, not that of the rulers.  If you are
-used to supporting the bosses and sysadmins in whatever they do, you
-might find this idea strange at first.
-
-
 @node timeout invocation
 @section @command{timeout}: Run a command with a time limit
 
diff -urNp coreutils-8.0-orig/doc/coreutils.texi.orig coreutils-8.0/doc/coreutils.texi.orig
--- coreutils-8.0-orig/doc/coreutils.texi.orig	1970-01-01 01:00:00.000000000 +0100
+++ coreutils-8.0/doc/coreutils.texi.orig	2009-09-29 15:27:54.000000000 +0200
@@ -0,0 +1,15835 @@
+\input texinfo
+@c %**start of header
+@setfilename coreutils.info
+@settitle @sc{gnu} Coreutils
+
+@c %**end of header
+
+@include version.texi
+@include constants.texi
+
+@c Define new indices.
+@defcodeindex op
+@defcodeindex fl
+
+@c Put everything in one index (arbitrarily chosen to be the concept index).
+@syncodeindex fl cp
+@syncodeindex fn cp
+@syncodeindex ky cp
+@syncodeindex op cp
+@syncodeindex pg cp
+@syncodeindex vr cp
+
+@dircategory Basics
+@direntry
+* Coreutils: (coreutils).       Core GNU (file, text, shell) utilities.
+* Common options: (coreutils)Common options.      Common options.
+* File permissions: (coreutils)File permissions.  Access modes.
+* Date input formats: (coreutils)Date input formats.
+@end direntry
+
+@c FIXME: the following need documentation
+@c * [: (coreutils)[ invocation.                   File/string tests.
+@c * pinky: (coreutils)pinky invocation.           FIXME.
+@c * mktemp: (coreutils)mktemp invocation.         FIXME.
+
+@dircategory Individual utilities
+@direntry
+* arch: (coreutils)arch invocation.             Print machine hardware name.
+* base64: (coreutils)base64 invocation.         Base64 encode/decode data.
+* basename: (coreutils)basename invocation.     Strip directory and suffix.
+* cat: (coreutils)cat invocation.               Concatenate and write files.
+* chcon: (coreutils)chcon invocation.           Change SELinux CTX of files.
+* chgrp: (coreutils)chgrp invocation.           Change file groups.
+* chmod: (coreutils)chmod invocation.           Change file permissions.
+* chown: (coreutils)chown invocation.           Change file owners/groups.
+* chroot: (coreutils)chroot invocation.         Specify the root directory.
+* cksum: (coreutils)cksum invocation.           Print POSIX CRC checksum.
+* comm: (coreutils)comm invocation.             Compare sorted files by line.
+* cp: (coreutils)cp invocation.                 Copy files.
+* csplit: (coreutils)csplit invocation.         Split by context.
+* cut: (coreutils)cut invocation.               Print selected parts of lines.
+* date: (coreutils)date invocation.             Print/set system date and time.
+* dd: (coreutils)dd invocation.                 Copy and convert a file.
+* df: (coreutils)df invocation.                 Report file system disk usage.
+* dir: (coreutils)dir invocation.               List directories briefly.
+* dircolors: (coreutils)dircolors invocation.   Color setup for ls.
+* dirname: (coreutils)dirname invocation.       Strip non-directory suffix.
+* du: (coreutils)du invocation.                 Report on disk usage.
+* echo: (coreutils)echo invocation.             Print a line of text.
+* env: (coreutils)env invocation.               Modify the environment.
+* expand: (coreutils)expand invocation.         Convert tabs to spaces.
+* expr: (coreutils)expr invocation.             Evaluate expressions.
+* factor: (coreutils)factor invocation.         Print prime factors
+* false: (coreutils)false invocation.           Do nothing, unsuccessfully.
+* fmt: (coreutils)fmt invocation.               Reformat paragraph text.
+* fold: (coreutils)fold invocation.             Wrap long input lines.
+* groups: (coreutils)groups invocation.         Print group names a user is in.
+* head: (coreutils)head invocation.             Output the first part of files.
+* hostid: (coreutils)hostid invocation.         Print numeric host identifier.
+* hostname: (coreutils)hostname invocation.     Print or set system name.
+* id: (coreutils)id invocation.                 Print user identity.
+* install: (coreutils)install invocation.       Copy and change attributes.
+* join: (coreutils)join invocation.             Join lines on a common field.
+* kill: (coreutils)kill invocation.             Send a signal to processes.
+* link: (coreutils)link invocation.             Make hard links between files.
+* ln: (coreutils)ln invocation.                 Make links between files.
+* logname: (coreutils)logname invocation.       Print current login name.
+* ls: (coreutils)ls invocation.                 List directory contents.
+* md5sum: (coreutils)md5sum invocation.         Print or check MD5 digests.
+* mkdir: (coreutils)mkdir invocation.           Create directories.
+* mkfifo: (coreutils)mkfifo invocation.         Create FIFOs (named pipes).
+* mknod: (coreutils)mknod invocation.           Create special files.
+* mv: (coreutils)mv invocation.                 Rename files.
+* nice: (coreutils)nice invocation.             Modify niceness.
+* nl: (coreutils)nl invocation.                 Number lines and write files.
+* nohup: (coreutils)nohup invocation.           Immunize to hangups.
+* od: (coreutils)od invocation.                 Dump files in octal, etc.
+* paste: (coreutils)paste invocation.           Merge lines of files.
+* pathchk: (coreutils)pathchk invocation.       Check file name portability.
+* pr: (coreutils)pr invocation.                 Paginate or columnate files.
+* printenv: (coreutils)printenv invocation.     Print environment variables.
+* printf: (coreutils)printf invocation.         Format and print data.
+* ptx: (coreutils)ptx invocation.               Produce permuted indexes.
+* pwd: (coreutils)pwd invocation.               Print working directory.
+* readlink: (coreutils)readlink invocation.     Print referent of a symlink.
+* rm: (coreutils)rm invocation.                 Remove files.
+* rmdir: (coreutils)rmdir invocation.           Remove empty directories.
+* runcon: (coreutils)runcon invocation.         Run in specified SELinux CTX.
+* seq: (coreutils)seq invocation.               Print numeric sequences
+* sha1sum: (coreutils)sha1sum invocation.       Print or check SHA-1 digests.
+* sha2: (coreutils)sha2 utilities.              Print or check SHA-2 digests.
+* shred: (coreutils)shred invocation.           Remove files more securely.
+* shuf: (coreutils)shuf invocation.             Shuffling text files.
+* sleep: (coreutils)sleep invocation.           Delay for a specified time.
+* sort: (coreutils)sort invocation.             Sort text files.
+* split: (coreutils)split invocation.           Split into fixed-size pieces.
+* stat: (coreutils)stat invocation.             Report file(system) status.
+* stdbuf: (coreutils)stdbuf invocation.         Modify stdio buffering.
+* stty: (coreutils)stty invocation.             Print/change terminal settings.
+* su: (coreutils)su invocation.                 Modify user and group ID.
+* sum: (coreutils)sum invocation.               Print traditional checksum.
+* sync: (coreutils)sync invocation.             Synchronize memory and disk.
+* tac: (coreutils)tac invocation.               Reverse files.
+* tail: (coreutils)tail invocation.             Output the last part of files.
+* tee: (coreutils)tee invocation.               Redirect to multiple files.
+* test: (coreutils)test invocation.             File/string tests.
+* timeout: (coreutils)timeout invocation.       Run with time limit.
+* touch: (coreutils)touch invocation.           Change file timestamps.
+* tr: (coreutils)tr invocation.                 Translate characters.
+* true: (coreutils)true invocation.             Do nothing, successfully.
+* truncate: (coreutils)truncate invocation.     Shrink/extend size of a file.
+* tsort: (coreutils)tsort invocation.           Topological sort.
+* tty: (coreutils)tty invocation.               Print terminal name.
+* uname: (coreutils)uname invocation.           Print system information.
+* unexpand: (coreutils)unexpand invocation.     Convert spaces to tabs.
+* uniq: (coreutils)uniq invocation.             Uniquify files.
+* unlink: (coreutils)unlink invocation.         Removal via unlink(2).
+* uptime: (coreutils)uptime invocation.         Print uptime and load.
+* users: (coreutils)users invocation.           Print current user names.
+* vdir: (coreutils)vdir invocation.             List directories verbosely.
+* wc: (coreutils)wc invocation.                 Line, word, and byte counts.
+* who: (coreutils)who invocation.               Print who is logged in.
+* whoami: (coreutils)whoami invocation.         Print effective user ID.
+* yes: (coreutils)yes invocation.               Print a string indefinitely.
+@end direntry
+
+@copying
+This manual documents version @value{VERSION} of the @sc{gnu} core
+utilities, including the standard programs for text and file manipulation.
+
+Copyright @copyright{} 1994-1996, 2000-2009 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+@end quotation
+@end copying
+
+@titlepage
+@title @sc{gnu} @code{Coreutils}
+@subtitle Core GNU utilities
+@subtitle for version @value{VERSION}, @value{UPDATED}
+@author David MacKenzie et al.
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+@shortcontents
+@contents
+
+@ifnottex
+@node Top
+@top GNU Coreutils
+
+@insertcopying
+@end ifnottex
+
+@cindex core utilities
+@cindex text utilities
+@cindex shell utilities
+@cindex file utilities
+
+@menu
+* Introduction::                 Caveats, overview, and authors
+* Common options::               Common options
+* Output of entire files::       cat tac nl od base64
+* Formatting file contents::     fmt pr fold
+* Output of parts of files::     head tail split csplit
+* Summarizing files::            wc sum cksum md5sum sha1sum sha2
+* Operating on sorted files::    sort shuf uniq comm ptx tsort
+* Operating on fields::          cut paste join
+* Operating on characters::      tr expand unexpand
+* Directory listing::            ls dir vdir dircolors
+* Basic operations::             cp dd install mv rm shred
+* Special file types::         mkdir rmdir unlink mkfifo mknod ln link readlink
+* Changing file attributes::     chgrp chmod chown touch
+* Disk usage::                   df du stat sync truncate
+* Printing text::                echo printf yes
+* Conditions::                   false true test expr
+* Redirection::                  tee
+* File name manipulation::       dirname basename pathchk
+* Working context::              pwd stty printenv tty
+* User information::             id logname whoami groups users who
+* System context::               date arch uname hostname hostid uptime
+* SELinux context::              chcon runcon
+* Modified command invocation::  chroot env nice nohup stdbuf su timeout
+* Process control::              kill
+* Delaying::                     sleep
+* Numeric operations::           factor seq
+* File permissions::             Access modes
+* Date input formats::           Specifying date strings
+* Opening the software toolbox:: The software tools philosophy
+* GNU Free Documentation License:: Copying and sharing this manual
+* Concept index::                General index
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Common Options
+
+* Exit status::                  Indicating program success or failure
+* Backup options::               Backup options
+* Block size::                   Block size
+* Signal specifications::        Specifying signals
+* Disambiguating names and IDs:: chgrp and chown owner and group syntax
+* Random sources::               Sources of random data
+* Target directory::             Target directory
+* Trailing slashes::             Trailing slashes
+* Traversing symlinks::          Traversing symlinks to directories
+* Treating / specially::         Treating / specially
+* Standards conformance::        Standards conformance
+
+Output of entire files
+
+* cat invocation::               Concatenate and write files
+* tac invocation::               Concatenate and write files in reverse
+* nl invocation::                Number lines and write files
+* od invocation::                Write files in octal or other formats
+* base64 invocation::            Transform data into printable data
+
+Formatting file contents
+
+* fmt invocation::               Reformat paragraph text
+* pr invocation::                Paginate or columnate files for printing
+* fold invocation::              Wrap input lines to fit in specified width
+
+Output of parts of files
+
+* head invocation::              Output the first part of files
+* tail invocation::              Output the last part of files
+* split invocation::             Split a file into fixed-size pieces
+* csplit invocation::            Split a file into context-determined pieces
+
+Summarizing files
+
+* wc invocation::                Print newline, word, and byte counts
+* sum invocation::               Print checksum and block counts
+* cksum invocation::             Print CRC checksum and byte counts
+* md5sum invocation::            Print or check MD5 digests
+* sha1sum invocation::           Print or check SHA-1 digests
+* sha2 utilities::               Print or check SHA-2 digests
+
+Operating on sorted files
+
+* sort invocation::              Sort text files
+* shuf invocation::              Shuffle text files
+* uniq invocation::              Uniquify files
+* comm invocation::              Compare two sorted files line by line
+* ptx invocation::               Produce a permuted index of file contents
+* tsort invocation::             Topological sort
+
+@command{ptx}: Produce permuted indexes
+
+* General options in ptx::       Options which affect general program behavior
+* Charset selection in ptx::     Underlying character set considerations
+* Input processing in ptx::      Input fields, contexts, and keyword selection
+* Output formatting in ptx::     Types of output format, and sizing the fields
+* Compatibility in ptx::         The @acronym{GNU} extensions to @command{ptx}
+
+Operating on fields
+
+* cut invocation::               Print selected parts of lines
+* paste invocation::             Merge lines of files
+* join invocation::              Join lines on a common field
+
+Operating on characters
+
+* tr invocation::                Translate, squeeze, and/or delete characters
+* expand invocation::            Convert tabs to spaces
+* unexpand invocation::          Convert spaces to tabs
+
+@command{tr}: Translate, squeeze, and/or delete characters
+
+* Character sets::               Specifying sets of characters
+* Translating::                  Changing one set of characters to another
+* Squeezing::                    Squeezing repeats and deleting
+
+Directory listing
+
+* ls invocation::                List directory contents
+* dir invocation::               Briefly list directory contents
+* vdir invocation::              Verbosely list directory contents
+* dircolors invocation::         Color setup for @command{ls}
+
+@command{ls}:  List directory contents
+
+* Which files are listed::       Which files are listed
+* What information is listed::   What information is listed
+* Sorting the output::           Sorting the output
+* Details about version sort::   More details about version sort
+* General output formatting::    General output formatting
+* Formatting the file names::    Formatting the file names
+
+Basic operations
+
+* cp invocation::                Copy files and directories
+* dd invocation::                Convert and copy a file
+* install invocation::           Copy files and set attributes
+* mv invocation::                Move (rename) files
+* rm invocation::                Remove files or directories
+* shred invocation::             Remove files more securely
+
+Special file types
+
+* link invocation::              Make a hard link via the link syscall
+* ln invocation::                Make links between files
+* mkdir invocation::             Make directories
+* mkfifo invocation::            Make FIFOs (named pipes)
+* mknod invocation::             Make block or character special files
+* readlink invocation::          Print value of a symlink or canonical file name
+* rmdir invocation::             Remove empty directories
+* unlink invocation::            Remove files via unlink syscall
+
+Changing file attributes
+
+* chown invocation::             Change file owner and group
+* chgrp invocation::             Change group ownership
+* chmod invocation::             Change access permissions
+* touch invocation::             Change file timestamps
+
+Disk usage
+
+* df invocation::                Report file system disk space usage
+* du invocation::                Estimate file space usage
+* stat invocation::              Report file or file system status
+* sync invocation::              Synchronize data on disk with memory
+* truncate invocation::          Shrink or extend the size of a file
+
+Printing text
+
+* echo invocation::              Print a line of text
+* printf invocation::            Format and print data
+* yes invocation::               Print a string until interrupted
+
+Conditions
+
+* false invocation::             Do nothing, unsuccessfully
+* true invocation::              Do nothing, successfully
+* test invocation::              Check file types and compare values
+* expr invocation::              Evaluate expressions
+
+@command{test}: Check file types and compare values
+
+* File type tests::              File type tests
+* Access permission tests::      Access permission tests
+* File characteristic tests::    File characteristic tests
+* String tests::                 String tests
+* Numeric tests::                Numeric tests
+
+@command{expr}: Evaluate expression
+
+* String expressions::           + : match substr index length
+* Numeric expressions::          + - * / %
+* Relations for expr::           | & < <= = == != >= >
+* Examples of expr::             Examples of using @command{expr}
+
+Redirection
+
+* tee invocation::               Redirect output to multiple files or processes
+
+File name manipulation
+
+* basename invocation::          Strip directory and suffix from a file name
+* dirname invocation::           Strip non-directory suffix from a file name
+* pathchk invocation::           Check file name validity and portability
+
+Working context
+
+* pwd invocation::               Print working directory
+* stty invocation::              Print or change terminal characteristics
+* printenv invocation::          Print all or some environment variables
+* tty invocation::               Print file name of terminal on standard input
+
+@command{stty}: Print or change terminal characteristics
+
+* Control::                      Control settings
+* Input::                        Input settings
+* Output::                       Output settings
+* Local::                        Local settings
+* Combination::                  Combination settings
+* Characters::                   Special characters
+* Special::                      Special settings
+
+User information
+
+* id invocation::                Print user identity
+* logname invocation::           Print current login name
+* whoami invocation::            Print effective user ID
+* groups invocation::            Print group names a user is in
+* users invocation::             Print login names of users currently logged in
+* who invocation::               Print who is currently logged in
+
+System context
+
+* arch invocation::              Print machine hardware name
+* date invocation::              Print or set system date and time
+* uname invocation::             Print system information
+* hostname invocation::          Print or set system name
+* hostid invocation::            Print numeric host identifier
+* uptime invocation::            Print system uptime and load
+
+@command{date}: Print or set system date and time
+
+* Time conversion specifiers::   %[HIklMNpPrRsSTXzZ]
+* Date conversion specifiers::   %[aAbBcCdDeFgGhjmuUVwWxyY]
+* Literal conversion specifiers:: %[%nt]
+* Padding and other flags::      Pad with zeros, spaces, etc.
+* Setting the time::             Changing the system clock
+* Options for date::             Instead of the current time
+* Date input formats::           Specifying date strings
+* Examples of date::             Examples
+
+SELinux context
+
+* chcon invocation::             Change SELinux context of file
+* runcon invocation::            Run a command in specified SELinux context
+
+Modified command invocation
+
+* chroot invocation::            Run a command with a different root directory
+* env invocation::               Run a command in a modified environment
+* nice invocation::              Run a command with modified niceness
+* nohup invocation::             Run a command immune to hangups
+* stdbuf invocation::            Run a command with modified I/O buffering
+* su invocation::                Run a command with substitute user and group ID
+* timeout invocation::           Run a command with a time limit
+
+Process control
+
+* kill invocation::              Sending a signal to processes.
+
+Delaying
+
+* sleep invocation::             Delay for a specified time
+
+Numeric operations
+
+* factor invocation::            Print prime factors
+* seq invocation::               Print numeric sequences
+
+File permissions
+
+* Mode Structure::               Structure of file mode bits
+* Symbolic Modes::               Mnemonic representation of file mode bits
+* Numeric Modes::                File mode bits as octal numbers
+* Directory Setuid and Setgid::  Set-user-ID and set-group-ID on directories
+
+Date input formats
+
+* General date syntax::          Common rules
+* Calendar date items::          19 Dec 1994
+* Time of day items::            9:20pm
+* Time zone items::              @sc{est}, @sc{pdt}, @sc{gmt}
+* Day of week items::            Monday and others
+* Relative items in date strings:: next tuesday, 2 years ago
+* Pure numbers in date strings:: 19931219, 1440
+* Seconds since the Epoch::      @@1078100502
+* Specifying time zone rules::   TZ="America/New_York", TZ="UTC0"
+* Authors of get_date::          Bellovin, Eggert, Salz, Berets, et al
+
+Opening the software toolbox
+
+* Toolbox introduction::         Toolbox introduction
+* I/O redirection::              I/O redirection
+* The who command::              The @command{who} command
+* The cut command::              The @command{cut} command
+* The sort command::             The @command{sort} command
+* The uniq command::             The @command{uniq} command
+* Putting the tools together::   Putting the tools together
+
+Copying This Manual
+
+* GNU Free Documentation License::     Copying and sharing this manual
+
+@end detailmenu
+@end menu
+
+
+@node Introduction
+@chapter Introduction
+
+This manual is a work in progress: many sections make no attempt to explain
+basic concepts in a way suitable for novices.  Thus, if you are interested,
+please get involved in improving this manual.  The entire @sc{gnu} community
+will benefit.
+
+@cindex @acronym{POSIX}
+The @sc{gnu} utilities documented here are mostly compatible with the
+@acronym{POSIX} standard.
+@cindex bugs, reporting
+Please report bugs to @email{bug-coreutils@@gnu.org}.  Remember
+to include the version number, machine architecture, input files, and
+any other information needed to reproduce the bug: your input, what you
+expected, what you got, and why it is wrong.  Diffs are welcome, but
+please include a description of the problem as well, since this is
+sometimes difficult to infer.  @xref{Bugs, , , gcc, Using and Porting GNU CC}.
+
+@cindex Berry, K.
+@cindex Paterson, R.
+@cindex Stallman, R.
+@cindex Pinard, F.
+@cindex MacKenzie, D.
+@cindex Meyering, J.
+@cindex Youmans, B.
+This manual was originally derived from the Unix man pages in the
+distributions, which were written by David MacKenzie and updated by Jim
+Meyering.  What you are reading now is the authoritative documentation
+for these utilities; the man pages are no longer being maintained.  The
+original @command{fmt} man page was written by Ross Paterson.  Fran@,{c}ois
+Pinard did the initial conversion to Texinfo format.  Karl Berry did the
+indexing, some reorganization, and editing of the results.  Brian
+Youmans of the Free Software Foundation office staff combined the
+manuals for textutils, fileutils, and sh-utils to produce the present
+omnibus manual.  Richard Stallman contributed his usual invaluable
+insights to the overall process.
+
+@node Common options
+@chapter Common options
+
+@macro optBackup
+@item -b
+@itemx @w{@kbd{--backup}[=@var{method}]}
+@opindex -b
+@opindex --backup
+@vindex VERSION_CONTROL
+@cindex backups, making
+@xref{Backup options}.
+Make a backup of each file that would otherwise be overwritten or removed.
+@end macro
+
+@macro optBackupSuffix
+@item -S @var{suffix}
+@itemx --suffix=@var{suffix}
+@opindex -S
+@opindex --suffix
+Append @var{suffix} to each backup file made with @option{-b}.
+@xref{Backup options}.
+@end macro
+
+@macro optTargetDirectory
+@item -t @var{directory}
+@itemx @w{@kbd{--target-directory}=@var{directory}}
+@opindex -t
+@opindex --target-directory
+@cindex target directory
+@cindex destination directory
+Specify the destination @var{directory}.
+@xref{Target directory}.
+@end macro
+
+@macro optNoTargetDirectory
+@item -T
+@itemx --no-target-directory
+@opindex -T
+@opindex --no-target-directory
+@cindex target directory
+@cindex destination directory
+Do not treat the last operand specially when it is a directory or a
+symbolic link to a directory.  @xref{Target directory}.
+@end macro
+
+@macro optSi
+@itemx --si
+@opindex --si
+@cindex SI output
+Append an SI-style abbreviation to each size, such as @samp{M} for
+megabytes.  Powers of 1000 are used, not 1024; @samp{M} stands for
+1,000,000 bytes.  This option is equivalent to
+@option{--block-size=si}.  Use the @option{-h} or
+@option{--human-readable} option if
+you prefer powers of 1024.
+@end macro
+
+@macro optHumanReadable
+@item -h
+@itemx --human-readable
+@opindex -h
+@opindex --human-readable
+@cindex human-readable output
+Append a size letter to each size, such as @samp{M} for mebibytes.
+Powers of 1024 are used, not 1000; @samp{M} stands for 1,048,576 bytes.
+This option is equivalent to @option{--block-size=human-readable}.
+Use the @option{--si} option if you prefer powers of 1000.
+@end macro
+
+@macro optStripTrailingSlashes
+@itemx @w{@kbd{--strip-trailing-slashes}}
+@opindex --strip-trailing-slashes
+@cindex stripping trailing slashes
+Remove any trailing slashes from each @var{source} argument.
+@xref{Trailing slashes}.
+@end macro
+
+@macro mayConflictWithShellBuiltIn{cmd}
+@cindex conflicts with shell built-ins
+@cindex built-in shell commands, conflicts with
+Due to shell aliases and built-in @command{\cmd\} command, using an
+unadorned @command{\cmd\} interactively or in a script may get you
+different functionality than that described here.  Invoke it via
+@command{env} (i.e., @code{env \cmd\ @dots{}}) to avoid interference
+from the shell.
+
+@end macro
+
+@macro multiplierSuffixes{varName}
+@var{\varName\} may be, or may be an integer optionally followed by,
+one of the following multiplicative suffixes:
+@example
+@samp{b}  =>            512 ("blocks")
+@samp{KB} =>           1000 (KiloBytes)
+@samp{K}  =>           1024 (KibiBytes)
+@samp{MB} =>      1000*1000 (MegaBytes)
+@samp{M}  =>      1024*1024 (MebiBytes)
+@samp{GB} => 1000*1000*1000 (GigaBytes)
+@samp{G}  => 1024*1024*1024 (GibiBytes)
+@end example
+and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}.
+@end macro
+
+@c FIXME: same as above, but no ``blocks'' line.
+@macro multiplierSuffixesNoBlocks{varName}
+@var{\varName\} may be, or may be an integer optionally followed by,
+one of the following multiplicative suffixes:
+@example
+@samp{KB} =>           1000 (KiloBytes)
+@samp{K}  =>           1024 (KibiBytes)
+@samp{MB} =>      1000*1000 (MegaBytes)
+@samp{M}  =>      1024*1024 (MebiBytes)
+@samp{GB} => 1000*1000*1000 (GigaBytes)
+@samp{G}  => 1024*1024*1024 (GibiBytes)
+@end example
+and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}.
+@end macro
+
+@cindex common options
+
+Certain options are available in all of these programs.  Rather than
+writing identical descriptions for each of the programs, they are
+described here.  (In fact, every @sc{gnu} program accepts (or should accept)
+these options.)
+
+@vindex POSIXLY_CORRECT
+Normally options and operands can appear in any order, and programs act
+as if all the options appear before any operands.  For example,
+@samp{sort -r passwd -t :} acts like @samp{sort -r -t : passwd}, since
+@samp{:} is an option-argument of @option{-t}.  However, if the
+@env{POSIXLY_CORRECT} environment variable is set, options must appear
+before operands, unless otherwise specified for a particular command.
+
+A few programs can usefully have trailing operands with leading
+@samp{-}.  With such a program, options must precede operands even if
+@env{POSIXLY_CORRECT} is not set, and this fact is noted in the
+program description.  For example, the @command{env} command's options
+must appear before its operands, since in some cases the operands
+specify a command that itself contains options.
+
+Most programs that accept long options recognize unambiguous
+abbreviations of those options.  For example, @samp{rmdir
+--ignore-fail-on-non-empty} can be invoked as @samp{rmdir
+--ignore-fail} or even @samp{rmdir --i}.  Ambiguous options, such as
+@samp{ls --h}, are identified as such.
+
+Some of these programs recognize the @option{--help} and @option{--version}
+options only when one of them is the sole command line argument.  For
+these programs, abbreviations of the long options are not always recognized.
+
+@table @samp
+
+@item --help
+@opindex --help
+@cindex help, online
+Print a usage message listing all available options, then exit successfully.
+
+@item --version
+@opindex --version
+@cindex version number, finding
+Print the version number, then exit successfully.
+
+@item --
+@opindex --
+@cindex option delimiter
+Delimit the option list.  Later arguments, if any, are treated as
+operands even if they begin with @samp{-}.  For example, @samp{sort --
+-r} reads from the file named @file{-r}.
+
+@end table
+
+@cindex standard input
+@cindex standard output
+A single @samp{-} operand is not really an option, though it looks like one.  It
+stands for standard input, or for standard output if that is clear from
+the context.  For example, @samp{sort -} reads from standard input,
+and is equivalent to plain @samp{sort}, and @samp{tee -} writes an
+extra copy of its input to standard output.  Unless otherwise
+specified, @samp{-} can appear as any operand that requires a file
+name.
+
+@menu
+* Exit status::                 Indicating program success or failure.
+* Backup options::              -b -S, in some programs.
+* Block size::                  BLOCK_SIZE and --block-size, in some programs.
+* Signal specifications::       Specifying signals using the --signal option.
+* Disambiguating names and IDs:: chgrp and chown owner and group syntax
+* Random sources::              --random-source, in some programs.
+* Target directory::            Specifying a target directory, in some programs.
+* Trailing slashes::            --strip-trailing-slashes, in some programs.
+* Traversing symlinks::         -H, -L, or -P, in some programs.
+* Treating / specially::        --preserve-root and --no-preserve-root.
+* Special built-in utilities::  @command{break}, @command{:}, @command{eval}, @dots{}
+* Standards conformance::       Conformance to the @acronym{POSIX} standard.
+@end menu
+
+
+@node Exit status
+@section Exit status
+
+@macro exitstatus
+An exit status of zero indicates success,
+and a nonzero value indicates failure.
+@end macro
+
+Nearly every command invocation yields an integral @dfn{exit status}
+that can be used to change how other commands work.
+For the vast majority of commands, an exit status of zero indicates
+success.  Failure is indicated by a nonzero value---typically
+@samp{1}, though it may differ on unusual platforms as @acronym{POSIX}
+requires only that it be nonzero.
+
+However, some of the programs documented here do produce
+other exit status values and a few associate different
+meanings with the values @samp{0} and @samp{1}.
+Here are some of the exceptions:
+@command{chroot}, @command{env}, @command{expr}, @command{nice},
+@command{nohup}, @command{printenv}, @command{sort}, @command{stdbuf},
+@command{su}, @command{test}, @command{timeout}, @command{tty}.
+
+
+@node Backup options
+@section Backup options
+
+@cindex backup options
+
+Some @sc{gnu} programs (at least @command{cp}, @command{install},
+@command{ln}, and @command{mv}) optionally make backups of files
+before writing new versions.
+These options control the details of these backups.  The options are also
+briefly mentioned in the descriptions of the particular programs.
+
+@table @samp
+
+@item -b
+@itemx @w{@kbd{--backup}[=@var{method}]}
+@opindex -b
+@opindex --backup
+@vindex VERSION_CONTROL
+@cindex backups, making
+Make a backup of each file that would otherwise be overwritten or removed.
+Without this option, the original versions are destroyed.
+Use @var{method} to determine the type of backups to make.
+When this option is used but @var{method} is not specified,
+then the value of the @env{VERSION_CONTROL}
+environment variable is used.  And if @env{VERSION_CONTROL} is not set,
+the default backup type is @samp{existing}.
+
+Note that the short form of this option, @option{-b} does not accept any
+argument.  Using @option{-b} is equivalent to using @option{--backup=existing}.
+
+@vindex version-control @r{Emacs variable}
+This option corresponds to the Emacs variable @samp{version-control};
+the values for @var{method} are the same as those used in Emacs.
+This option also accepts more descriptive names.
+The valid @var{method}s are (unique abbreviations are accepted):
+
+@table @samp
+@item none
+@itemx off
+@opindex none @r{backup method}
+Never make backups.
+
+@item numbered
+@itemx t
+@opindex numbered @r{backup method}
+Always make numbered backups.
+
+@item existing
+@itemx nil
+@opindex existing @r{backup method}
+Make numbered backups of files that already have them, simple backups
+of the others.
+
+@item simple
+@itemx never
+@opindex simple @r{backup method}
+Always make simple backups.  Please note @samp{never} is not to be
+confused with @samp{none}.
+
+@end table
+
+@item -S @var{suffix}
+@itemx --suffix=@var{suffix}
+@opindex -S
+@opindex --suffix
+@cindex backup suffix
+@vindex SIMPLE_BACKUP_SUFFIX
+Append @var{suffix} to each backup file made with @option{-b}.  If this
+option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX}
+environment variable is used.  And if @env{SIMPLE_BACKUP_SUFFIX} is not
+set, the default is @samp{~}, just as in Emacs.
+
+@end table
+
+@node Block size
+@section Block size
+
+@cindex block size
+
+Some @sc{gnu} programs (at least @command{df}, @command{du}, and
+@command{ls}) display sizes in ``blocks''.  You can adjust the block size
+and method of display to make sizes easier to read.  The block size
+used for display is independent of any file system block size.
+Fractional block counts are rounded up to the nearest integer.
+
+@opindex --block-size=@var{size}
+@vindex BLOCKSIZE
+@vindex BLOCK_SIZE
+@vindex DF_BLOCK_SIZE
+@vindex DU_BLOCK_SIZE
+@vindex LS_BLOCK_SIZE
+@vindex POSIXLY_CORRECT@r{, and block size}
+
+The default block size is chosen by examining the following environment
+variables in turn; the first one that is set determines the block size.
+
+@table @code
+
+@item DF_BLOCK_SIZE
+This specifies the default block size for the @command{df} command.
+Similarly, @env{DU_BLOCK_SIZE} specifies the default for @command{du} and
+@env{LS_BLOCK_SIZE} for @command{ls}.
+
+@item BLOCK_SIZE
+This specifies the default block size for all three commands, if the
+above command-specific environment variables are not set.
+
+@item BLOCKSIZE
+This specifies the default block size for all values that are normally
+printed as blocks, if neither @env{BLOCK_SIZE} nor the above
+command-specific environment variables are set.  Unlike the other
+environment variables, @env{BLOCKSIZE} does not affect values that are
+normally printed as byte counts, e.g., the file sizes contained in
+@code{ls -l} output.
+
+@item POSIXLY_CORRECT
+If neither @env{@var{command}_BLOCK_SIZE}, nor @env{BLOCK_SIZE}, nor
+@env{BLOCKSIZE} is set, but this variable is set, the block size
+defaults to 512.
+
+@end table
+
+If none of the above environment variables are set, the block size
+currently defaults to 1024 bytes in most contexts, but this number may
+change in the future.  For @command{ls} file sizes, the block size
+defaults to 1 byte.
+
+@cindex human-readable output
+@cindex SI output
+
+A block size specification can be a positive integer specifying the number
+of bytes per block, or it can be @code{human-readable} or @code{si} to
+select a human-readable format.  Integers may be followed by suffixes
+that are upward compatible with the
+@uref{http://www.bipm.fr/enus/3_SI/si-prefixes.html, SI prefixes}
+for decimal multiples and with the
+@uref{http://physics.nist.gov/cuu/Units/binary.html, IEC 60027-2
+prefixes for binary multiples}.
+
+With human-readable formats, output sizes are followed by a size letter
+such as @samp{M} for megabytes.  @code{BLOCK_SIZE=human-readable} uses
+powers of 1024; @samp{M} stands for 1,048,576 bytes.
+@code{BLOCK_SIZE=si} is similar, but uses powers of 1000 and appends
+@samp{B}; @samp{MB} stands for 1,000,000 bytes.
+
+@vindex LC_NUMERIC
+A block size specification preceded by @samp{'} causes output sizes to
+be displayed with thousands separators.  The @env{LC_NUMERIC} locale
+specifies the thousands separator and grouping.  For example, in an
+American English locale, @samp{--block-size="'1kB"} would cause a size
+of 1234000 bytes to be displayed as @samp{1,234}.  In the default C
+locale, there is no thousands separator so a leading @samp{'} has no
+effect.
+
+An integer block size can be followed by a suffix to specify a
+multiple of that size.  A bare size letter,
+or one followed by @samp{iB}, specifies
+a multiple using powers of 1024.  A size letter followed by @samp{B}
+specifies powers of 1000 instead.  For example, @samp{1M} and
+@samp{1MiB} are equivalent to @samp{1048576}, whereas @samp{1MB} is
+equivalent to @samp{1000000}.
+
+A plain suffix without a preceding integer acts as if @samp{1} were
+prepended, except that it causes a size indication to be appended to
+the output.  For example, @samp{--block-size="kB"} displays 3000 as
+@samp{3kB}.
+
+The following suffixes are defined.  Large sizes like @code{1Y}
+may be rejected by your computer due to limitations of its arithmetic.
+
+@table @samp
+@item kB
+@cindex kilobyte, definition of
+kilobyte: @math{10^3 = 1000}.
+@item k
+@itemx K
+@itemx KiB
+@cindex kibibyte, definition of
+kibibyte: @math{2^{10} = 1024}.  @samp{K} is special: the SI prefix is
+@samp{k} and the IEC 60027-2 prefix is @samp{Ki}, but tradition and
+@acronym{POSIX} use @samp{k} to mean @samp{KiB}.
+@item MB
+@cindex megabyte, definition of
+megabyte: @math{10^6 = 1,000,000}.
+@item M
+@itemx MiB
+@cindex mebibyte, definition of
+mebibyte: @math{2^{20} = 1,048,576}.
+@item GB
+@cindex gigabyte, definition of
+gigabyte: @math{10^9 = 1,000,000,000}.
+@item G
+@itemx GiB
+@cindex gibibyte, definition of
+gibibyte: @math{2^{30} = 1,073,741,824}.
+@item TB
+@cindex terabyte, definition of
+terabyte:  @math{10^{12} = 1,000,000,000,000}.
+@item T
+@itemx TiB
+@cindex tebibyte, definition of
+tebibyte: @math{2^{40} = 1,099,511,627,776}.
+@item PB
+@cindex petabyte, definition of
+petabyte: @math{10^{15} = 1,000,000,000,000,000}.
+@item P
+@itemx PiB
+@cindex pebibyte, definition of
+pebibyte: @math{2^{50} = 1,125,899,906,842,624}.
+@item EB
+@cindex exabyte, definition of
+exabyte: @math{10^{18} = 1,000,000,000,000,000,000}.
+@item E
+@itemx EiB
+@cindex exbibyte, definition of
+exbibyte: @math{2^{60} = 1,152,921,504,606,846,976}.
+@item ZB
+@cindex zettabyte, definition of
+zettabyte: @math{10^{21} = 1,000,000,000,000,000,000,000}
+@item Z
+@itemx ZiB
+@math{2^{70} = 1,180,591,620,717,411,303,424}.
+(@samp{Zi} is a @acronym{GNU} extension to IEC 60027-2.)
+@item YB
+@cindex yottabyte, definition of
+yottabyte: @math{10^{24} = 1,000,000,000,000,000,000,000,000}.
+@item Y
+@itemx YiB
+@math{2^{80} = 1,208,925,819,614,629,174,706,176}.
+(@samp{Yi} is a @acronym{GNU} extension to IEC 60027-2.)
+@end table
+
+@opindex -k
+@opindex -h
+@opindex --block-size
+@opindex --human-readable
+@opindex --si
+
+Block size defaults can be overridden by an explicit
+@option{--block-size=@var{size}} option.  The @option{-k}
+option is equivalent to @option{--block-size=1K}, which
+is the default unless the @env{POSIXLY_CORRECT} environment variable is
+set.  The @option{-h} or @option{--human-readable} option is equivalent to
+@option{--block-size=human-readable}.  The @option{--si} option is
+equivalent to @option{--block-size=si}.
+
+@node Signal specifications
+@section Signal specifications
+@cindex signals, specifying
+
+A @var{signal} may be a signal name like @samp{HUP}, or a signal
+number like @samp{1}, or an exit status of a process terminated by the
+signal.  A signal name can be given in canonical form or prefixed by
+@samp{SIG}.  The case of the letters is ignored. The following signal names
+and numbers are supported on all @acronym{POSIX} compliant systems:
+
+@table @samp
+@item HUP
+1.  Hangup.
+@item INT
+2.  Terminal interrupt.
+@item QUIT
+3.  Terminal quit.
+@item ABRT
+6.  Process abort.
+@item KILL
+9.  Kill (cannot be caught or ignored).
+@item ALRM
+14.  Alarm Clock.
+@item TERM
+15.  Termination.
+@end table
+
+@noindent
+Other supported signal names have system-dependent corresponding
+numbers.  All systems conforming to @acronym{POSIX} 1003.1-2001 also
+support the following signals:
+
+@table @samp
+@item BUS
+Access to an undefined portion of a memory object.
+@item CHLD
+Child process terminated, stopped, or continued.
+@item CONT
+Continue executing, if stopped.
+@item FPE
+Erroneous arithmetic operation.
+@item ILL
+Illegal Instruction.
+@item PIPE
+Write on a pipe with no one to read it.
+@item SEGV
+Invalid memory reference.
+@item STOP
+Stop executing (cannot be caught or ignored).
+@item TSTP
+Terminal stop.
+@item TTIN
+Background process attempting read.
+@item TTOU
+Background process attempting write.
+@item URG
+High bandwidth data is available at a socket.
+@item USR1
+User-defined signal 1.
+@item USR2
+User-defined signal 2.
+@end table
+
+@noindent
+@acronym{POSIX} 1003.1-2001 systems that support the @acronym{XSI} extension
+also support the following signals:
+
+@table @samp
+@item POLL
+Pollable event.
+@item PROF
+Profiling timer expired.
+@item SYS
+Bad system call.
+@item TRAP
+Trace/breakpoint trap.
+@item VTALRM
+Virtual timer expired.
+@item XCPU
+CPU time limit exceeded.
+@item XFSZ
+File size limit exceeded.
+@end table
+
+@noindent
+@acronym{POSIX} 1003.1-2001 systems that support the @acronym{XRT} extension
+also support at least eight real-time signals called @samp{RTMIN},
+@samp{RTMIN+1}, @dots{}, @samp{RTMAX-1}, @samp{RTMAX}.
+
+@node Disambiguating names and IDs
+@section chown and chgrp: Disambiguating user names and IDs
+@cindex user names, disambiguating
+@cindex user IDs, disambiguating
+@cindex group names, disambiguating
+@cindex group IDs, disambiguating
+@cindex disambiguating group names and IDs
+
+Since the @var{owner} and @var{group} arguments to @command{chown} and
+@command{chgrp} may be specified as names or numeric IDs, there is an
+apparent ambiguity.
+What if a user or group @emph{name} is a string of digits?
+@footnote{Using a number as a user name is common in some environments.}
+Should the command interpret it as a user name or as an ID?
+@acronym{POSIX} requires that @command{chown} and @command{chgrp}
+first attempt to resolve the specified string as a name, and
+only once that fails, then try to interpret it as an ID.
+This is troublesome when you want to specify a numeric ID, say 42,
+and it must work even in a pathological situation where
+@samp{42} is a user name that maps to some other user ID, say 1000.
+Simply invoking @code{chown 42 F}, will set @file{F}s owner ID to
+1000---not what you intended.
+
+GNU @command{chown} and @command{chgrp} provide a way to work around this,
+that at the same time may result in a significant performance improvement
+by eliminating a database look-up.
+Simply precede each numeric user ID and/or group ID with a @samp{+},
+in order to force its interpretation as an integer:
+
+@example
+chown +42 F
+chgrp +$numeric_group_id another-file
+chown +0:+0 /
+@end example
+
+GNU @command{chown} and @command{chgrp}
+skip the name look-up process for each @samp{+}-prefixed string,
+because a string containing @samp{+} is never a valid user or group name.
+This syntax is accepted on most common Unix systems, but not on Solaris 10.
+
+@node Random sources
+@section Sources of random data
+
+@cindex random sources
+
+The @command{shuf}, @command{shred}, and @command{sort} commands
+sometimes need random data to do their work.  For example, @samp{sort
+-R} must choose a hash function at random, and it needs random data to
+make this selection.
+
+By default these commands use an internal pseudorandom generator
+initialized by a small amount of entropy, but can be directed to use
+an external source with the @option{--random-source=@var{file}} option.
+An error is reported if @var{file} does not contain enough bytes.
+
+For example, the device file @file{/dev/urandom} could be used as the
+source of random data.  Typically, this device gathers environmental
+noise from device drivers and other sources into an entropy pool, and
+uses the pool to generate random bits.  If the pool is short of data,
+the device reuses the internal pool to produce more bits, using a
+cryptographically secure pseudorandom number generator.  But be aware
+that this device is not designed for bulk random data generation
+and is relatively slow.
+
+@file{/dev/urandom} suffices for most practical uses, but applications
+requiring high-value or long-term protection of private data may
+require an alternate data source like @file{/dev/random} or
+@file{/dev/arandom}.  The set of available sources depends on your
+operating system.
+
+To reproduce the results of an earlier invocation of a command, you
+can save some random data into a file and then use that file as the
+random source in earlier and later invocations of the command.
+
+@node Target directory
+@section Target directory
+
+@cindex target directory
+
+The @command{cp}, @command{install}, @command{ln}, and @command{mv}
+commands normally treat the last operand specially when it is a
+directory or a symbolic link to a directory.  For example, @samp{cp
+source dest} is equivalent to @samp{cp source dest/source} if
+@file{dest} is a directory.  Sometimes this behavior is not exactly
+what is wanted, so these commands support the following options to
+allow more fine-grained control:
+
+@table @samp
+
+@item -T
+@itemx --no-target-directory
+@opindex --no-target-directory
+@cindex target directory
+@cindex destination directory
+Do not treat the last operand specially when it is a directory or a
+symbolic link to a directory.  This can help avoid race conditions in
+programs that operate in a shared area.  For example, when the command
+@samp{mv /tmp/source /tmp/dest} succeeds, there is no guarantee that
+@file{/tmp/source} was renamed to @file{/tmp/dest}: it could have been
+renamed to @file{/tmp/dest/source} instead, if some other process
+created @file{/tmp/dest} as a directory.  However, if @file{mv
+-T /tmp/source /tmp/dest} succeeds, there is no
+question that @file{/tmp/source} was renamed to @file{/tmp/dest}.
+
+In the opposite situation, where you want the last operand to be
+treated as a directory and want a diagnostic otherwise, you can use
+the @option{--target-directory} (@option{-t}) option.
+
+@item -t @var{directory}
+@itemx @w{@kbd{--target-directory}=@var{directory}}
+@opindex --target-directory
+@cindex target directory
+@cindex destination directory
+Use @var{directory} as the directory component of each destination
+file name.
+
+The interface for most programs is that after processing options and a
+finite (possibly zero) number of fixed-position arguments, the remaining
+argument list is either expected to be empty, or is a list of items
+(usually files) that will all be handled identically.  The @command{xargs}
+program is designed to work well with this convention.
+
+The commands in the @command{mv}-family are unusual in that they take
+a variable number of arguments with a special case at the @emph{end}
+(namely, the target directory).  This makes it nontrivial to perform some
+operations, e.g., ``move all files from here to ../d/'', because
+@code{mv * ../d/} might exhaust the argument space, and @code{ls | xargs ...}
+doesn't have a clean way to specify an extra final argument for each
+invocation of the subject command.  (It can be done by going through a
+shell command, but that requires more human labor and brain power than
+it should.)
+
+The @w{@kbd{--target-directory}} (@option{-t}) option allows the @command{cp},
+@command{install}, @command{ln}, and @command{mv} programs to be used
+conveniently with @command{xargs}.  For example, you can move the files
+from the current directory to a sibling directory, @code{d} like this:
+
+@smallexample
+ls | xargs mv -t ../d --
+@end smallexample
+
+However, this doesn't move files whose names begin with @samp{.}.
+If you use the @sc{gnu} @command{find} program, you can move those
+files too, with this command:
+
+@example
+find . -mindepth 1 -maxdepth 1 \
+  | xargs mv -t ../d
+@end example
+
+But both of the above approaches fail if there are no files in the
+current directory, or if any file has a name containing a blank or
+some other special characters.
+The following example removes those limitations and requires both
+@sc{gnu} @command{find} and @sc{gnu} @command{xargs}:
+
+@example
+find . -mindepth 1 -maxdepth 1 -print0 \
+  | xargs --null --no-run-if-empty \
+      mv -t ../d
+@end example
+
+@end table
+
+@noindent
+The @option{--target-directory} (@option{-t}) and
+@option{--no-target-directory} (@option{-T})
+options cannot be combined.
+
+@node Trailing slashes
+@section Trailing slashes
+
+@cindex trailing slashes
+
+Some @sc{gnu} programs (at least @command{cp} and @command{mv}) allow you to
+remove any trailing slashes from each @var{source} argument before
+operating on it.  The @w{@kbd{--strip-trailing-slashes}} option enables
+this behavior.
+
+This is useful when a @var{source} argument may have a trailing slash and
+@c FIXME: mv's behavior in this case is system-dependent
+specify a symbolic link to a directory.  This scenario is in fact rather
+common because some shells can automatically append a trailing slash when
+performing file name completion on such symbolic links.  Without this
+option, @command{mv}, for example, (via the system's rename function) must
+interpret a trailing slash as a request to dereference the symbolic link
+and so must rename the indirectly referenced @emph{directory} and not
+the symbolic link.  Although it may seem surprising that such behavior
+be the default, it is required by @acronym{POSIX} and is consistent with
+other parts of that standard.
+
+@node Traversing symlinks
+@section Traversing symlinks
+
+@cindex symbolic link to directory, controlling traversal of
+
+The following options modify how @command{chown} and @command{chgrp}
+@c FIXME: note that `du' has these options, too, but they have slightly
+@c different meaning.
+traverse a hierarchy when the @option{--recursive} (@option{-R})
+option is also specified.
+If more than one of the following options is specified, only the final
+one takes effect.
+These options specify whether processing a symbolic link to a directory
+entails operating on just the symbolic link or on all files in the
+hierarchy rooted at that directory.
+
+These options are independent of @option{--dereference} and
+@option{--no-dereference} (@option{-h}), which control whether to modify
+a symlink or its referent.
+
+@table @samp
+
+@macro choptH
+@item -H
+@opindex -H
+@cindex symbolic link to directory, traverse each that is specified on the command line
+If @option{--recursive} (@option{-R}) is specified and
+a command line argument is a symbolic link to a directory, traverse it.
+@end macro
+@choptH
+
+@macro choptL
+@item -L
+@opindex -L
+@cindex symbolic link to directory, traverse each that is encountered
+In a recursive traversal, traverse every symbolic link to a directory
+that is encountered.
+@end macro
+@choptL
+
+@macro choptP
+@item -P
+@opindex -P
+@cindex symbolic link to directory, never traverse
+Do not traverse any symbolic links.
+This is the default if none of @option{-H}, @option{-L},
+or @option{-P} is specified.
+@end macro
+@choptP
+
+@end table
+
+
+@node Treating / specially
+@section Treating @file{/} specially
+
+Certain commands can operate destructively on entire hierarchies.
+For example, if a user with appropriate privileges mistakenly runs
+@samp{rm -rf / tmp/junk}, that may remove
+all files on the entire system.  Since there are so few
+legitimate uses for such a command,
+@sc{gnu} @command{rm} normally declines to operate on any directory
+that resolves to @file{/}.  If you really want to try to remove all
+the files on your system, you can use the @option{--no-preserve-root}
+option, but the default behavior, specified by the
+@option{--preserve-option}, is safer for most purposes.
+
+The commands @command{chgrp}, @command{chmod} and @command{chown}
+can also operate destructively on entire hierarchies, so they too
+support these options.  Although, unlike @command{rm}, they don't
+actually unlink files, these commands are arguably more dangerous
+when operating recursively on @file{/}, since they often work much
+more quickly, and hence damage more files before an alert user can
+interrupt them.  Tradition and @acronym{POSIX} require these commands
+to operate recursively on @file{/}, so they default to
+@option{--no-preserve-root}, but using the @option{--preserve-root}
+option makes them safer for most purposes.  For convenience you can
+specify @option{--preserve-root} in an alias or in a shell function.
+
+Note that the @option{--preserve-root} option also ensures
+that @command{chgrp} and @command{chown} do not modify @file{/}
+even when dereferencing a symlink pointing to @file{/}.
+
+@node Special built-in utilities
+@section Special built-in utilities
+
+Some programs like @command{nice} can invoke other programs; for
+example, the command @samp{nice cat file} invokes the program
+@command{cat} by executing the command @samp{cat file}.  However,
+@dfn{special built-in utilities} like @command{exit} cannot be invoked
+this way.  For example, the command @samp{nice exit} does not have a
+well-defined behavior: it may generate an error message instead of
+exiting.
+
+Here is a list of the special built-in utilities that are standardized
+by @acronym{POSIX} 1003.1-2004.
+
+@quotation
+@t{.@: : break continue eval exec exit export readonly
+return set shift times trap unset}
+@end quotation
+
+For example, because @samp{.}, @samp{:}, and @samp{exec} are special,
+the commands @samp{nice . foo.sh}, @samp{nice :}, and @samp{nice exec
+pwd} do not work as you might expect.
+
+Many shells extend this list.  For example, Bash has several extra
+special built-in utilities like @command{history}, and
+@command{suspend}, and with Bash the command @samp{nice suspend}
+generates an error message instead of suspending.
+
+@node Standards conformance
+@section Standards conformance
+
+@vindex POSIXLY_CORRECT
+In a few cases, the @sc{gnu} utilities' default behavior is
+incompatible with the @acronym{POSIX} standard.  To suppress these
+incompatibilities, define the @env{POSIXLY_CORRECT} environment
+variable.  Unless you are checking for @acronym{POSIX} conformance, you
+probably do not need to define @env{POSIXLY_CORRECT}.
+
+Newer versions of @acronym{POSIX} are occasionally incompatible with older
+versions.  For example, older versions of @acronym{POSIX} required the
+command @samp{sort +1} to sort based on the second and succeeding
+fields in each input line, but starting with @acronym{POSIX} 1003.1-2001
+the same command is required to sort the file named @file{+1}, and you
+must instead use the command @samp{sort -k 2} to get the field-based
+sort.
+
+@vindex _POSIX2_VERSION
+The @sc{gnu} utilities normally conform to the version of @acronym{POSIX}
+that is standard for your system.  To cause them to conform to a
+different version of @acronym{POSIX}, define the @env{_POSIX2_VERSION}
+environment variable to a value of the form @var{yyyymm} specifying
+the year and month the standard was adopted.  Two values are currently
+supported for @env{_POSIX2_VERSION}: @samp{199209} stands for
+@acronym{POSIX} 1003.2-1992, and @samp{200112} stands for @acronym{POSIX}
+1003.1-2001.  For example, if you have a newer system but are running software
+that assumes an older version of @acronym{POSIX} and uses @samp{sort +1}
+or @samp{tail +10}, you can work around any compatibility problems by setting
+@samp{_POSIX2_VERSION=199209} in your environment.
+
+@node Output of entire files
+@chapter Output of entire files
+
+@cindex output of entire files
+@cindex entire files, output of
+
+These commands read and write entire files, possibly transforming them
+in some way.
+
+@menu
+* cat invocation::              Concatenate and write files.
+* tac invocation::              Concatenate and write files in reverse.
+* nl invocation::               Number lines and write files.
+* od invocation::               Write files in octal or other formats.
+* base64 invocation::           Transform data into printable data.
+@end menu
+
+@node cat invocation
+@section @command{cat}: Concatenate and write files
+
+@pindex cat
+@cindex concatenate and write files
+@cindex copying files
+
+@command{cat} copies each @var{file} (@samp{-} means standard input), or
+standard input if none are given, to standard output.  Synopsis:
+