17715 lines
586 KiB
Diff
17715 lines
586 KiB
Diff
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:
|
|
+
|
|
+@example
|
|
+cat [@var{option}] [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -A
|
|
+@itemx --show-all
|
|
+@opindex -A
|
|
+@opindex --show-all
|
|
+Equivalent to @option{-vET}.
|
|
+
|
|
+@item -b
|
|
+@itemx --number-nonblank
|
|
+@opindex -b
|
|
+@opindex --number-nonblank
|
|
+Number all nonempty output lines, starting with 1.
|
|
+
|
|
+@item -e
|
|
+@opindex -e
|
|
+Equivalent to @option{-vE}.
|
|
+
|
|
+@item -E
|
|
+@itemx --show-ends
|
|
+@opindex -E
|
|
+@opindex --show-ends
|
|
+Display a @samp{$} after the end of each line.
|
|
+
|
|
+@item -n
|
|
+@itemx --number
|
|
+@opindex -n
|
|
+@opindex --number
|
|
+Number all output lines, starting with 1.
|
|
+
|
|
+@item -s
|
|
+@itemx --squeeze-blank
|
|
+@opindex -s
|
|
+@opindex --squeeze-blank
|
|
+@cindex squeezing empty lines
|
|
+Suppress repeated adjacent empty lines; output just one empty line
|
|
+instead of several.
|
|
+
|
|
+@item -t
|
|
+@opindex -t
|
|
+Equivalent to @option{-vT}.
|
|
+
|
|
+@item -T
|
|
+@itemx --show-tabs
|
|
+@opindex -T
|
|
+@opindex --show-tabs
|
|
+Display TAB characters as @samp{^I}.
|
|
+
|
|
+@item -u
|
|
+@opindex -u
|
|
+Ignored; for @acronym{POSIX} compatibility.
|
|
+
|
|
+@item -v
|
|
+@itemx --show-nonprinting
|
|
+@opindex -v
|
|
+@opindex --show-nonprinting
|
|
+Display control characters except for LFD and TAB using
|
|
+@samp{^} notation and precede characters that have the high bit set with
|
|
+@samp{M-}.
|
|
+
|
|
+@end table
|
|
+
|
|
+On systems like MS-DOS that distinguish between text and binary files,
|
|
+@command{cat} normally reads and writes in binary mode. However,
|
|
+@command{cat} reads in text mode if one of the options
|
|
+@option{-bensAE} is used or if @command{cat} is reading from standard
|
|
+input and standard input is a terminal. Similarly, @command{cat}
|
|
+writes in text mode if one of the options @option{-bensAE} is used or
|
|
+if standard output is a terminal.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+Examples:
|
|
+
|
|
+@smallexample
|
|
+# Output f's contents, then standard input, then g's contents.
|
|
+cat f - g
|
|
+
|
|
+# Copy standard input to standard output.
|
|
+cat
|
|
+@end smallexample
|
|
+
|
|
+
|
|
+@node tac invocation
|
|
+@section @command{tac}: Concatenate and write files in reverse
|
|
+
|
|
+@pindex tac
|
|
+@cindex reversing files
|
|
+
|
|
+@command{tac} copies each @var{file} (@samp{-} means standard input), or
|
|
+standard input if none are given, to standard output, reversing the
|
|
+records (lines by default) in each separately. Synopsis:
|
|
+
|
|
+@example
|
|
+tac [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+@dfn{Records} are separated by instances of a string (newline by
|
|
+default). By default, this separator string is attached to the end of
|
|
+the record that it follows in the file.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -b
|
|
+@itemx --before
|
|
+@opindex -b
|
|
+@opindex --before
|
|
+The separator is attached to the beginning of the record that it
|
|
+precedes in the file.
|
|
+
|
|
+@item -r
|
|
+@itemx --regex
|
|
+@opindex -r
|
|
+@opindex --regex
|
|
+Treat the separator string as a regular expression. Users of @command{tac}
|
|
+on MS-DOS/MS-Windows should note that, since @command{tac} reads files in
|
|
+binary mode, each line of a text file might end with a CR/LF pair
|
|
+instead of the Unix-style LF.
|
|
+
|
|
+@item -s @var{separator}
|
|
+@itemx --separator=@var{separator}
|
|
+@opindex -s
|
|
+@opindex --separator
|
|
+Use @var{separator} as the record separator, instead of newline.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node nl invocation
|
|
+@section @command{nl}: Number lines and write files
|
|
+
|
|
+@pindex nl
|
|
+@cindex numbering lines
|
|
+@cindex line numbering
|
|
+
|
|
+@command{nl} writes each @var{file} (@samp{-} means standard input), or
|
|
+standard input if none are given, to standard output, with line numbers
|
|
+added to some or all of the lines. Synopsis:
|
|
+
|
|
+@example
|
|
+nl [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+@cindex logical pages, numbering on
|
|
+@command{nl} decomposes its input into (logical) pages; by default, the
|
|
+line number is reset to 1 at the top of each logical page. @command{nl}
|
|
+treats all of the input files as a single document; it does not reset
|
|
+line numbers or logical pages between files.
|
|
+
|
|
+@cindex headers, numbering
|
|
+@cindex body, numbering
|
|
+@cindex footers, numbering
|
|
+A logical page consists of three sections: header, body, and footer.
|
|
+Any of the sections can be empty. Each can be numbered in a different
|
|
+style from the others.
|
|
+
|
|
+The beginnings of the sections of logical pages are indicated in the
|
|
+input file by a line containing exactly one of these delimiter strings:
|
|
+
|
|
+@table @samp
|
|
+@item \:\:\:
|
|
+start of header;
|
|
+@item \:\:
|
|
+start of body;
|
|
+@item \:
|
|
+start of footer.
|
|
+@end table
|
|
+
|
|
+The two characters from which these strings are made can be changed from
|
|
+@samp{\} and @samp{:} via options (see below), but the pattern and
|
|
+length of each string cannot be changed.
|
|
+
|
|
+A section delimiter is replaced by an empty line on output. Any text
|
|
+that comes before the first section delimiter string in the input file
|
|
+is considered to be part of a body section, so @command{nl} treats a
|
|
+file that contains no section delimiters as a single body section.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -b @var{style}
|
|
+@itemx --body-numbering=@var{style}
|
|
+@opindex -b
|
|
+@opindex --body-numbering
|
|
+Select the numbering style for lines in the body section of each
|
|
+logical page. When a line is not numbered, the current line number
|
|
+is not incremented, but the line number separator character is still
|
|
+prepended to the line. The styles are:
|
|
+
|
|
+@table @samp
|
|
+@item a
|
|
+number all lines,
|
|
+@item t
|
|
+number only nonempty lines (default for body),
|
|
+@item n
|
|
+do not number lines (default for header and footer),
|
|
+@item p@var{bre}
|
|
+number only lines that contain a match for the basic regular
|
|
+expression @var{bre}.
|
|
+@xref{Regular Expressions, , Regular Expressions, grep, The GNU Grep Manual}.
|
|
+@end table
|
|
+
|
|
+@item -d @var{cd}
|
|
+@itemx --section-delimiter=@var{cd}
|
|
+@opindex -d
|
|
+@opindex --section-delimiter
|
|
+@cindex section delimiters of pages
|
|
+Set the section delimiter characters to @var{cd}; default is
|
|
+@samp{\:}. If only @var{c} is given, the second remains @samp{:}.
|
|
+(Remember to protect @samp{\} or other metacharacters from shell
|
|
+expansion with quotes or extra backslashes.)
|
|
+
|
|
+@item -f @var{style}
|
|
+@itemx --footer-numbering=@var{style}
|
|
+@opindex -f
|
|
+@opindex --footer-numbering
|
|
+Analogous to @option{--body-numbering}.
|
|
+
|
|
+@item -h @var{style}
|
|
+@itemx --header-numbering=@var{style}
|
|
+@opindex -h
|
|
+@opindex --header-numbering
|
|
+Analogous to @option{--body-numbering}.
|
|
+
|
|
+@item -i @var{number}
|
|
+@itemx --line-increment=@var{number}
|
|
+@opindex -i
|
|
+@opindex --line-increment
|
|
+Increment line numbers by @var{number} (default 1).
|
|
+
|
|
+@item -l @var{number}
|
|
+@itemx --join-blank-lines=@var{number}
|
|
+@opindex -l
|
|
+@opindex --join-blank-lines
|
|
+@cindex empty lines, numbering
|
|
+@cindex blank lines, numbering
|
|
+Consider @var{number} (default 1) consecutive empty lines to be one
|
|
+logical line for numbering, and only number the last one. Where fewer
|
|
+than @var{number} consecutive empty lines occur, do not number them.
|
|
+An empty line is one that contains no characters, not even spaces
|
|
+or tabs.
|
|
+
|
|
+@item -n @var{format}
|
|
+@itemx --number-format=@var{format}
|
|
+@opindex -n
|
|
+@opindex --number-format
|
|
+Select the line numbering format (default is @code{rn}):
|
|
+
|
|
+@table @samp
|
|
+@item ln
|
|
+@opindex ln @r{format for @command{nl}}
|
|
+left justified, no leading zeros;
|
|
+@item rn
|
|
+@opindex rn @r{format for @command{nl}}
|
|
+right justified, no leading zeros;
|
|
+@item rz
|
|
+@opindex rz @r{format for @command{nl}}
|
|
+right justified, leading zeros.
|
|
+@end table
|
|
+
|
|
+@item -p
|
|
+@itemx --no-renumber
|
|
+@opindex -p
|
|
+@opindex --no-renumber
|
|
+Do not reset the line number at the start of a logical page.
|
|
+
|
|
+@item -s @var{string}
|
|
+@itemx --number-separator=@var{string}
|
|
+@opindex -s
|
|
+@opindex --number-separator
|
|
+Separate the line number from the text line in the output with
|
|
+@var{string} (default is the TAB character).
|
|
+
|
|
+@item -v @var{number}
|
|
+@itemx --starting-line-number=@var{number}
|
|
+@opindex -v
|
|
+@opindex --starting-line-number
|
|
+Set the initial line number on each logical page to @var{number} (default 1).
|
|
+
|
|
+@item -w @var{number}
|
|
+@itemx --number-width=@var{number}
|
|
+@opindex -w
|
|
+@opindex --number-width
|
|
+Use @var{number} characters for line numbers (default 6).
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node od invocation
|
|
+@section @command{od}: Write files in octal or other formats
|
|
+
|
|
+@pindex od
|
|
+@cindex octal dump of files
|
|
+@cindex hex dump of files
|
|
+@cindex ASCII dump of files
|
|
+@cindex file contents, dumping unambiguously
|
|
+
|
|
+@command{od} writes an unambiguous representation of each @var{file}
|
|
+(@samp{-} means standard input), or standard input if none are given.
|
|
+Synopses:
|
|
+
|
|
+@smallexample
|
|
+od [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+od [-abcdfilosx]@dots{} [@var{file}] [[+]@var{offset}[.][b]]
|
|
+od [@var{option}]@dots{} --traditional [@var{file}] [[+]@var{offset}[.][b] [[+]@var{label}[.][b]]]
|
|
+@end smallexample
|
|
+
|
|
+Each line of output consists of the offset in the input, followed by
|
|
+groups of data from the file. By default, @command{od} prints the offset in
|
|
+octal, and each group of file data is a C @code{short int}'s worth of input
|
|
+printed as a single octal number.
|
|
+
|
|
+If @var{offset} is given, it specifies how many input bytes to skip
|
|
+before formatting and writing. By default, it is interpreted as an
|
|
+octal number, but the optional trailing decimal point causes it to be
|
|
+interpreted as decimal. If no decimal is specified and the offset
|
|
+begins with @samp{0x} or @samp{0X} it is interpreted as a hexadecimal
|
|
+number. If there is a trailing @samp{b}, the number of bytes skipped
|
|
+will be @var{offset} multiplied by 512.
|
|
+
|
|
+If a command is of both the first and second forms, the second form is
|
|
+assumed if the last operand begins with @samp{+} or (if there are two
|
|
+operands) a digit. For example, in @samp{od foo 10} and @samp{od +10}
|
|
+the @samp{10} is an offset, whereas in @samp{od 10} the @samp{10} is a
|
|
+file name.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -A @var{radix}
|
|
+@itemx --address-radix=@var{radix}
|
|
+@opindex -A
|
|
+@opindex --address-radix
|
|
+@cindex radix for file offsets
|
|
+@cindex file offset radix
|
|
+Select the base in which file offsets are printed. @var{radix} can
|
|
+be one of the following:
|
|
+
|
|
+@table @samp
|
|
+@item d
|
|
+decimal;
|
|
+@item o
|
|
+octal;
|
|
+@item x
|
|
+hexadecimal;
|
|
+@item n
|
|
+none (do not print offsets).
|
|
+@end table
|
|
+
|
|
+The default is octal.
|
|
+
|
|
+@item -j @var{bytes}
|
|
+@itemx --skip-bytes=@var{bytes}
|
|
+@opindex -j
|
|
+@opindex --skip-bytes
|
|
+Skip @var{bytes} input bytes before formatting and writing. If
|
|
+@var{bytes} begins with @samp{0x} or @samp{0X}, it is interpreted in
|
|
+hexadecimal; otherwise, if it begins with @samp{0}, in octal; otherwise,
|
|
+in decimal.
|
|
+@multiplierSuffixes{bytes}
|
|
+
|
|
+@item -N @var{bytes}
|
|
+@itemx --read-bytes=@var{bytes}
|
|
+@opindex -N
|
|
+@opindex --read-bytes
|
|
+Output at most @var{bytes} bytes of the input. Prefixes and suffixes on
|
|
+@code{bytes} are interpreted as for the @option{-j} option.
|
|
+
|
|
+@item -S @var{bytes}
|
|
+@itemx --strings[=@var{bytes}]
|
|
+@opindex -S
|
|
+@opindex --strings
|
|
+@cindex string constants, outputting
|
|
+Instead of the normal output, output only @dfn{string constants}: at
|
|
+least @var{bytes} consecutive @acronym{ASCII} graphic characters,
|
|
+followed by a zero byte (@acronym{ASCII} @sc{nul}).
|
|
+Prefixes and suffixes on @code{bytes} are interpreted as for the
|
|
+@option{-j} option.
|
|
+
|
|
+If @var{n} is omitted with @option{--strings}, the default is 3.
|
|
+
|
|
+@item -t @var{type}
|
|
+@itemx --format=@var{type}
|
|
+@opindex -t
|
|
+@opindex --format
|
|
+Select the format in which to output the file data. @var{type} is a
|
|
+string of one or more of the below type indicator characters. If you
|
|
+include more than one type indicator character in a single @var{type}
|
|
+string, or use this option more than once, @command{od} writes one copy
|
|
+of each output line using each of the data types that you specified,
|
|
+in the order that you specified.
|
|
+
|
|
+Adding a trailing ``z'' to any type specification appends a display
|
|
+of the @acronym{ASCII} character representation of the printable characters
|
|
+to the output line generated by the type specification.
|
|
+
|
|
+@table @samp
|
|
+@item a
|
|
+named character, ignoring high-order bit
|
|
+@item c
|
|
+@acronym{ASCII} character or backslash escape,
|
|
+@item d
|
|
+signed decimal
|
|
+@item f
|
|
+floating point
|
|
+@item o
|
|
+octal
|
|
+@item u
|
|
+unsigned decimal
|
|
+@item x
|
|
+hexadecimal
|
|
+@end table
|
|
+
|
|
+The type @code{a} outputs things like @samp{sp} for space, @samp{nl} for
|
|
+newline, and @samp{nul} for a zero byte. Only the least significant
|
|
+seven bits of each byte is used; the high-order bit is ignored.
|
|
+Type @code{c} outputs
|
|
+@samp{ }, @samp{\n}, and @code{\0}, respectively.
|
|
+
|
|
+@cindex type size
|
|
+Except for types @samp{a} and @samp{c}, you can specify the number
|
|
+of bytes to use in interpreting each number in the given data type
|
|
+by following the type indicator character with a decimal integer.
|
|
+Alternately, you can specify the size of one of the C compiler's
|
|
+built-in data types by following the type indicator character with
|
|
+one of the following characters. For integers (@samp{d}, @samp{o},
|
|
+@samp{u}, @samp{x}):
|
|
+
|
|
+@table @samp
|
|
+@item C
|
|
+char
|
|
+@item S
|
|
+short
|
|
+@item I
|
|
+int
|
|
+@item L
|
|
+long
|
|
+@end table
|
|
+
|
|
+For floating point (@code{f}):
|
|
+
|
|
+@table @asis
|
|
+@item F
|
|
+float
|
|
+@item D
|
|
+double
|
|
+@item L
|
|
+long double
|
|
+@end table
|
|
+
|
|
+@item -v
|
|
+@itemx --output-duplicates
|
|
+@opindex -v
|
|
+@opindex --output-duplicates
|
|
+Output consecutive lines that are identical. By default, when two or
|
|
+more consecutive output lines would be identical, @command{od} outputs only
|
|
+the first line, and puts just an asterisk on the following line to
|
|
+indicate the elision.
|
|
+
|
|
+@item -w[@var{n}]
|
|
+@itemx --width[=@var{n}]
|
|
+@opindex -w
|
|
+@opindex --width
|
|
+Dump @code{n} input bytes per output line. This must be a multiple of
|
|
+the least common multiple of the sizes associated with the specified
|
|
+output types.
|
|
+
|
|
+If this option is not given at all, the default is 16. If @var{n} is
|
|
+omitted, the default is 32.
|
|
+
|
|
+@end table
|
|
+
|
|
+The next several options are shorthands for format specifications.
|
|
+@sc{gnu} @command{od} accepts any combination of shorthands and format
|
|
+specification options. These options accumulate.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -a
|
|
+@opindex -a
|
|
+Output as named characters. Equivalent to @samp{-t a}.
|
|
+
|
|
+@item -b
|
|
+@opindex -b
|
|
+Output as octal bytes. Equivalent to @samp{-t o1}.
|
|
+
|
|
+@item -c
|
|
+@opindex -c
|
|
+Output as @acronym{ASCII} characters or backslash escapes. Equivalent to
|
|
+@samp{-t c}.
|
|
+
|
|
+@item -d
|
|
+@opindex -d
|
|
+Output as unsigned decimal two-byte units. Equivalent to @samp{-t u2}.
|
|
+
|
|
+@item -f
|
|
+@opindex -f
|
|
+Output as floats. Equivalent to @samp{-t fF}.
|
|
+
|
|
+@item -i
|
|
+@opindex -i
|
|
+Output as decimal ints. Equivalent to @samp{-t dI}.
|
|
+
|
|
+@item -l
|
|
+@opindex -l
|
|
+Output as decimal long ints. Equivalent to @samp{-t dL}.
|
|
+
|
|
+@item -o
|
|
+@opindex -o
|
|
+Output as octal two-byte units. Equivalent to @option{-t o2}.
|
|
+
|
|
+@item -s
|
|
+@opindex -s
|
|
+Output as decimal two-byte units. Equivalent to @option{-t d2}.
|
|
+
|
|
+@item -x
|
|
+@opindex -x
|
|
+Output as hexadecimal two-byte units. Equivalent to @samp{-t x2}.
|
|
+
|
|
+@item --traditional
|
|
+@opindex --traditional
|
|
+Recognize the non-option label argument that traditional @command{od}
|
|
+accepted. The following syntax:
|
|
+
|
|
+@smallexample
|
|
+od --traditional [@var{file}] [[+]@var{offset}[.][b] [[+]@var{label}[.][b]]]
|
|
+@end smallexample
|
|
+
|
|
+@noindent
|
|
+can be used to specify at most one file and optional arguments
|
|
+specifying an offset and a pseudo-start address, @var{label}.
|
|
+The @var{label} argument is interpreted
|
|
+just like @var{offset}, but it specifies an initial pseudo-address. The
|
|
+pseudo-addresses are displayed in parentheses following any normal
|
|
+address.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+@node base64 invocation
|
|
+@section @command{base64}: Transform data into printable data
|
|
+
|
|
+@pindex base64
|
|
+@cindex base64 encoding
|
|
+
|
|
+@command{base64} transforms data read from a file, or standard input,
|
|
+into (or from) base64 encoded form. The base64 encoded form uses
|
|
+printable @acronym{ASCII} characters to represent binary data.
|
|
+Synopses:
|
|
+
|
|
+@smallexample
|
|
+base64 [@var{option}]@dots{} [@var{file}]
|
|
+base64 --decode [@var{option}]@dots{} [@var{file}]
|
|
+@end smallexample
|
|
+
|
|
+The base64 encoding expands data to roughly 133% of the original.
|
|
+The format conforms to
|
|
+@uref{ftp://ftp.rfc-editor.org/in-notes/rfc4648.txt, RFC 4648}.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -w @var{cols}
|
|
+@itemx --wrap=@var{cols}
|
|
+@opindex -w
|
|
+@opindex --wrap
|
|
+@cindex wrap data
|
|
+@cindex column to wrap data after
|
|
+During encoding, wrap lines after @var{cols} characters. This must be
|
|
+a positive number.
|
|
+
|
|
+The default is to wrap after 76 characters. Use the value 0 to
|
|
+disable line wrapping altogether.
|
|
+
|
|
+@item -d
|
|
+@itemx --decode
|
|
+@opindex -d
|
|
+@opindex --decode
|
|
+@cindex Decode base64 data
|
|
+@cindex Base64 decoding
|
|
+Change the mode of operation, from the default of encoding data, to
|
|
+decoding data. Input is expected to be base64 encoded data, and the
|
|
+output will be the original data.
|
|
+
|
|
+@item -i
|
|
+@itemx --ignore-garbage
|
|
+@opindex -i
|
|
+@opindex --ignore-garbage
|
|
+@cindex Ignore garbage in base64 stream
|
|
+When decoding, newlines are always accepted.
|
|
+During decoding, ignore unrecognized bytes,
|
|
+to permit distorted data to be decoded.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node Formatting file contents
|
|
+@chapter Formatting file contents
|
|
+
|
|
+@cindex formatting file contents
|
|
+
|
|
+These commands reformat the contents of files.
|
|
+
|
|
+@menu
|
|
+* fmt invocation:: Reformat paragraph text.
|
|
+* pr invocation:: Paginate or columnate files for printing.
|
|
+* fold invocation:: Wrap input lines to fit in specified width.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node fmt invocation
|
|
+@section @command{fmt}: Reformat paragraph text
|
|
+
|
|
+@pindex fmt
|
|
+@cindex reformatting paragraph text
|
|
+@cindex paragraphs, reformatting
|
|
+@cindex text, reformatting
|
|
+
|
|
+@command{fmt} fills and joins lines to produce output lines of (at most)
|
|
+a given number of characters (75 by default). Synopsis:
|
|
+
|
|
+@example
|
|
+fmt [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+@command{fmt} reads from the specified @var{file} arguments (or standard
|
|
+input if none are given), and writes to standard output.
|
|
+
|
|
+By default, blank lines, spaces between words, and indentation are
|
|
+preserved in the output; successive input lines with different
|
|
+indentation are not joined; tabs are expanded on input and introduced on
|
|
+output.
|
|
+
|
|
+@cindex line-breaking
|
|
+@cindex sentences and line-breaking
|
|
+@cindex Knuth, Donald E.
|
|
+@cindex Plass, Michael F.
|
|
+@command{fmt} prefers breaking lines at the end of a sentence, and tries to
|
|
+avoid line breaks after the first word of a sentence or before the last
|
|
+word of a sentence. A @dfn{sentence break} is defined as either the end
|
|
+of a paragraph or a word ending in any of @samp{.?!}, followed by two
|
|
+spaces or end of line, ignoring any intervening parentheses or quotes.
|
|
+Like @TeX{}, @command{fmt} reads entire ``paragraphs'' before choosing line
|
|
+breaks; the algorithm is a variant of that given by Donald E. Knuth
|
|
+and Michael F. Plass in ``Breaking Paragraphs Into Lines'',
|
|
+@cite{Software---Practice & Experience} @b{11}, 11 (November 1981),
|
|
+1119--1184.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -c
|
|
+@itemx --crown-margin
|
|
+@opindex -c
|
|
+@opindex --crown-margin
|
|
+@cindex crown margin
|
|
+@dfn{Crown margin} mode: preserve the indentation of the first two
|
|
+lines within a paragraph, and align the left margin of each subsequent
|
|
+line with that of the second line.
|
|
+
|
|
+@item -t
|
|
+@itemx --tagged-paragraph
|
|
+@opindex -t
|
|
+@opindex --tagged-paragraph
|
|
+@cindex tagged paragraphs
|
|
+@dfn{Tagged paragraph} mode: like crown margin mode, except that if
|
|
+indentation of the first line of a paragraph is the same as the
|
|
+indentation of the second, the first line is treated as a one-line
|
|
+paragraph.
|
|
+
|
|
+@item -s
|
|
+@itemx --split-only
|
|
+@opindex -s
|
|
+@opindex --split-only
|
|
+Split lines only. Do not join short lines to form longer ones. This
|
|
+prevents sample lines of code, and other such ``formatted'' text from
|
|
+being unduly combined.
|
|
+
|
|
+@item -u
|
|
+@itemx --uniform-spacing
|
|
+@opindex -u
|
|
+@opindex --uniform-spacing
|
|
+Uniform spacing. Reduce spacing between words to one space, and spacing
|
|
+between sentences to two spaces.
|
|
+
|
|
+@item -@var{width}
|
|
+@itemx -w @var{width}
|
|
+@itemx --width=@var{width}
|
|
+@opindex -@var{width}
|
|
+@opindex -w
|
|
+@opindex --width
|
|
+Fill output lines up to @var{width} characters (default 75). @command{fmt}
|
|
+initially tries to make lines about 7% shorter than this, to give it
|
|
+room to balance line lengths.
|
|
+
|
|
+@item -p @var{prefix}
|
|
+@itemx --prefix=@var{prefix}
|
|
+Only lines beginning with @var{prefix} (possibly preceded by whitespace)
|
|
+are subject to formatting. The prefix and any preceding whitespace are
|
|
+stripped for the formatting and then re-attached to each formatted output
|
|
+line. One use is to format certain kinds of program comments, while
|
|
+leaving the code unchanged.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node pr invocation
|
|
+@section @command{pr}: Paginate or columnate files for printing
|
|
+
|
|
+@pindex pr
|
|
+@cindex printing, preparing files for
|
|
+@cindex multicolumn output, generating
|
|
+@cindex merging files in parallel
|
|
+
|
|
+@command{pr} writes each @var{file} (@samp{-} means standard input), or
|
|
+standard input if none are given, to standard output, paginating and
|
|
+optionally outputting in multicolumn format; optionally merges all
|
|
+@var{file}s, printing all in parallel, one per column. Synopsis:
|
|
+
|
|
+@example
|
|
+pr [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+@vindex LC_MESSAGES
|
|
+By default, a 5-line header is printed at each page: two blank lines;
|
|
+a line with the date, the file name, and the page count; and two more
|
|
+blank lines. A footer of five blank lines is also printed.
|
|
+The default @var{page_length} is 66
|
|
+lines. The default number of text lines is therefore 56.
|
|
+The text line of the header takes the form
|
|
+@samp{@var{date} @var{string} @var{page}}, with spaces inserted around
|
|
+@var{string} so that the line takes up the full @var{page_width}. Here,
|
|
+@var{date} is the date (see the @option{-D} or @option{--date-format}
|
|
+option for details), @var{string} is the centered header string, and
|
|
+@var{page} identifies the page number. The @env{LC_MESSAGES} locale
|
|
+category affects the spelling of @var{page}; in the default C locale, it
|
|
+is @samp{Page @var{number}} where @var{number} is the decimal page
|
|
+number.
|
|
+
|
|
+Form feeds in the input cause page breaks in the output. Multiple form
|
|
+feeds produce empty pages.
|
|
+
|
|
+Columns are of equal width, separated by an optional string (default
|
|
+is @samp{space}). For multicolumn output, lines will always be truncated to
|
|
+@var{page_width} (default 72), unless you use the @option{-J} option.
|
|
+For single
|
|
+column output no line truncation occurs by default. Use @option{-W} option to
|
|
+truncate lines in that case.
|
|
+
|
|
+The following changes were made in version 1.22i and apply to later
|
|
+versions of @command{pr}:
|
|
+@c FIXME: this whole section here sounds very awkward to me. I
|
|
+@c made a few small changes, but really it all needs to be redone. - Brian
|
|
+@c OK, I fixed another sentence or two, but some of it I just don't understand.
|
|
+@ - Brian
|
|
+@itemize @bullet
|
|
+
|
|
+@item
|
|
+Some small @var{letter options} (@option{-s}, @option{-w}) have been
|
|
+redefined for better @acronym{POSIX} compliance. The output of some further
|
|
+cases has been adapted to other Unix systems. These changes are not
|
|
+compatible with earlier versions of the program.
|
|
+
|
|
+@item
|
|
+Some @var{new capital letter} options (@option{-J}, @option{-S}, @option{-W})
|
|
+have been introduced to turn off unexpected interferences of small letter
|
|
+options. The @option{-N} option and the second argument @var{last_page}
|
|
+of @samp{+FIRST_PAGE} offer more flexibility. The detailed handling of
|
|
+form feeds set in the input files requires the @option{-T} option.
|
|
+
|
|
+@item
|
|
+Capital letter options override small letter ones.
|
|
+
|
|
+@item
|
|
+Some of the option-arguments (compare @option{-s}, @option{-e},
|
|
+@option{-i}, @option{-n}) cannot be specified as separate arguments from the
|
|
+preceding option letter (already stated in the @acronym{POSIX} specification).
|
|
+@end itemize
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item +@var{first_page}[:@var{last_page}]
|
|
+@itemx --pages=@var{first_page}[:@var{last_page}]
|
|
+@c The two following @opindex lines evoke warnings because they contain `:'
|
|
+@c The `info' spec does not permit that. If we use those lines, we end
|
|
+@c up with truncated index entries that don't work.
|
|
+@c @opindex +@var{first_page}[:@var{last_page}]
|
|
+@c @opindex --pages=@var{first_page}[:@var{last_page}]
|
|
+@opindex +@var{page_range}
|
|
+@opindex --pages=@var{page_range}
|
|
+Begin printing with page @var{first_page} and stop with @var{last_page}.
|
|
+Missing @samp{:@var{last_page}} implies end of file. While estimating
|
|
+the number of skipped pages each form feed in the input file results
|
|
+in a new page. Page counting with and without @samp{+@var{first_page}}
|
|
+is identical. By default, counting starts with the first page of input
|
|
+file (not first page printed). Line numbering may be altered by @option{-N}
|
|
+option.
|
|
+
|
|
+@item -@var{column}
|
|
+@itemx --columns=@var{column}
|
|
+@opindex -@var{column}
|
|
+@opindex --columns
|
|
+@cindex down columns
|
|
+With each single @var{file}, produce @var{column} columns of output
|
|
+(default is 1) and print columns down, unless @option{-a} is used. The
|
|
+column width is automatically decreased as @var{column} increases; unless
|
|
+you use the @option{-W/-w} option to increase @var{page_width} as well.
|
|
+This option might well cause some lines to be truncated. The number of
|
|
+lines in the columns on each page are balanced. The options @option{-e}
|
|
+and @option{-i} are on for multiple text-column output. Together with
|
|
+@option{-J} option column alignment and line truncation is turned off.
|
|
+Lines of full length are joined in a free field format and @option{-S}
|
|
+option may set field separators. @option{-@var{column}} may not be used
|
|
+with @option{-m} option.
|
|
+
|
|
+@item -a
|
|
+@itemx --across
|
|
+@opindex -a
|
|
+@opindex --across
|
|
+@cindex across columns
|
|
+With each single @var{file}, print columns across rather than down. The
|
|
+@option{-@var{column}} option must be given with @var{column} greater than one.
|
|
+If a line is too long to fit in a column, it is truncated.
|
|
+
|
|
+@item -c
|
|
+@itemx --show-control-chars
|
|
+@opindex -c
|
|
+@opindex --show-control-chars
|
|
+Print control characters using hat notation (e.g., @samp{^G}); print
|
|
+other nonprinting characters in octal backslash notation. By default,
|
|
+nonprinting characters are not changed.
|
|
+
|
|
+@item -d
|
|
+@itemx --double-space
|
|
+@opindex -d
|
|
+@opindex --double-space
|
|
+@cindex double spacing
|
|
+Double space the output.
|
|
+
|
|
+@item -D @var{format}
|
|
+@itemx --date-format=@var{format}
|
|
+@cindex time formats
|
|
+@cindex formatting times
|
|
+Format header dates using @var{format}, using the same conventions as
|
|
+for the command @samp{date +@var{format}}; @xref{date invocation}.
|
|
+Except for directives, which start with
|
|
+@samp{%}, characters in @var{format} are printed unchanged. You can use
|
|
+this option to specify an arbitrary string in place of the header date,
|
|
+e.g., @option{--date-format="Monday morning"}.
|
|
+
|
|
+@vindex POSIXLY_CORRECT
|
|
+@vindex LC_TIME
|
|
+The default date format is @samp{%Y-%m-%d %H:%M} (for example,
|
|
+@samp{2001-12-04 23:59});
|
|
+but if the @env{POSIXLY_CORRECT} environment variable is set
|
|
+and the @env{LC_TIME} locale category specifies the @acronym{POSIX}
|
|
+locale, the default is @samp{%b %e %H:%M %Y} (for example,
|
|
+@samp{Dec@ @ 4 23:59 2001}.
|
|
+
|
|
+@vindex TZ
|
|
+Time stamps are listed according to the time zone rules specified by
|
|
+the @env{TZ} environment variable, or by the system default rules if
|
|
+@env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone
|
|
+with @env{TZ}, libc, The GNU C Library Reference Manual}.
|
|
+
|
|
+@item -e[@var{in-tabchar}[@var{in-tabwidth}]]
|
|
+@itemx --expand-tabs[=@var{in-tabchar}[@var{in-tabwidth}]]
|
|
+@opindex -e
|
|
+@opindex --expand-tabs
|
|
+@cindex input tabs
|
|
+Expand @var{tab}s to spaces on input. Optional argument @var{in-tabchar} is
|
|
+the input tab character (default is the TAB character). Second optional
|
|
+argument @var{in-tabwidth} is the input tab character's width (default
|
|
+is 8).
|
|
+
|
|
+@item -f
|
|
+@itemx -F
|
|
+@itemx --form-feed
|
|
+@opindex -F
|
|
+@opindex -f
|
|
+@opindex --form-feed
|
|
+Use a form feed instead of newlines to separate output pages. This does
|
|
+not alter the default page length of 66 lines.
|
|
+
|
|
+@item -h @var{header}
|
|
+@itemx --header=@var{header}
|
|
+@opindex -h
|
|
+@opindex --header
|
|
+Replace the file name in the header with the centered string @var{header}.
|
|
+When using the shell, @var{header} should be quoted and should be
|
|
+separated from @option{-h} by a space.
|
|
+
|
|
+@item -i[@var{out-tabchar}[@var{out-tabwidth}]]
|
|
+@itemx --output-tabs[=@var{out-tabchar}[@var{out-tabwidth}]]
|
|
+@opindex -i
|
|
+@opindex --output-tabs
|
|
+@cindex output tabs
|
|
+Replace spaces with @var{tab}s on output. Optional argument @var{out-tabchar}
|
|
+is the output tab character (default is the TAB character). Second optional
|
|
+argument @var{out-tabwidth} is the output tab character's width (default
|
|
+is 8).
|
|
+
|
|
+@item -J
|
|
+@itemx --join-lines
|
|
+@opindex -J
|
|
+@opindex --join-lines
|
|
+Merge lines of full length. Used together with the column options
|
|
+@option{-@var{column}}, @option{-a -@var{column}} or @option{-m}. Turns off
|
|
+@option{-W/-w} line truncation;
|
|
+no column alignment used; may be used with
|
|
+@option{--sep-string[=@var{string}]}. @option{-J} has been introduced
|
|
+(together with @option{-W} and @option{--sep-string})
|
|
+to disentangle the old (@acronym{POSIX}-compliant) options @option{-w} and
|
|
+@option{-s} along with the three column options.
|
|
+
|
|
+
|
|
+@item -l @var{page_length}
|
|
+@itemx --length=@var{page_length}
|
|
+@opindex -l
|
|
+@opindex --length
|
|
+Set the page length to @var{page_length} (default 66) lines, including
|
|
+the lines of the header [and the footer]. If @var{page_length} is less
|
|
+than or equal to 10, the header and footer are omitted, as if the
|
|
+@option{-t} option had been given.
|
|
+
|
|
+@item -m
|
|
+@itemx --merge
|
|
+@opindex -m
|
|
+@opindex --merge
|
|
+Merge and print all @var{file}s in parallel, one in each column. If a
|
|
+line is too long to fit in a column, it is truncated, unless the @option{-J}
|
|
+option is used. @option{--sep-string[=@var{string}]} may be used.
|
|
+Empty pages in
|
|
+some @var{file}s (form feeds set) produce empty columns, still marked
|
|
+by @var{string}. The result is a continuous line numbering and column
|
|
+marking throughout the whole merged file. Completely empty merged pages
|
|
+show no separators or line numbers. The default header becomes
|
|
+@samp{@var{date} @var{page}} with spaces inserted in the middle; this
|
|
+may be used with the @option{-h} or @option{--header} option to fill up
|
|
+the middle blank part.
|
|
+
|
|
+@item -n[@var{number-separator}[@var{digits}]]
|
|
+@itemx --number-lines[=@var{number-separator}[@var{digits}]]
|
|
+@opindex -n
|
|
+@opindex --number-lines
|
|
+Provide @var{digits} digit line numbering (default for @var{digits} is
|
|
+5). With multicolumn output the number occupies the first @var{digits}
|
|
+column positions of each text column or only each line of @option{-m}
|
|
+output. With single column output the number precedes each line just as
|
|
+@option{-m} does. Default counting of the line numbers starts with the
|
|
+first line of the input file (not the first line printed, compare the
|
|
+@option{--page} option and @option{-N} option).
|
|
+Optional argument @var{number-separator} is the character appended to
|
|
+the line number to separate it from the text followed. The default
|
|
+separator is the TAB character. In a strict sense a TAB is always
|
|
+printed with single column output only. The TAB width varies
|
|
+with the TAB position, e.g., with the left @var{margin} specified
|
|
+by @option{-o} option. With multicolumn output priority is given to
|
|
+@samp{equal width of output columns} (a @acronym{POSIX} specification).
|
|
+The TAB width is fixed to the value of the first column and does
|
|
+not change with different values of left @var{margin}. That means a
|
|
+fixed number of spaces is always printed in the place of the
|
|
+@var{number-separator} TAB. The tabification depends upon the output
|
|
+position.
|
|
+
|
|
+@item -N @var{line_number}
|
|
+@itemx --first-line-number=@var{line_number}
|
|
+@opindex -N
|
|
+@opindex --first-line-number
|
|
+Start line counting with the number @var{line_number} at first line of
|
|
+first page printed (in most cases not the first line of the input file).
|
|
+
|
|
+@item -o @var{margin}
|
|
+@itemx --indent=@var{margin}
|
|
+@opindex -o
|
|
+@opindex --indent
|
|
+@cindex indenting lines
|
|
+@cindex left margin
|
|
+Indent each line with a margin @var{margin} spaces wide (default is zero).
|
|
+The total page width is the size of the margin plus the @var{page_width}
|
|
+set with the @option{-W/-w} option. A limited overflow may occur with
|
|
+numbered single column output (compare @option{-n} option).
|
|
+
|
|
+@item -r
|
|
+@itemx --no-file-warnings
|
|
+@opindex -r
|
|
+@opindex --no-file-warnings
|
|
+Do not print a warning message when an argument @var{file} cannot be
|
|
+opened. (The exit status will still be nonzero, however.)
|
|
+
|
|
+@item -s[@var{char}]
|
|
+@itemx --separator[=@var{char}]
|
|
+@opindex -s
|
|
+@opindex --separator
|
|
+Separate columns by a single character @var{char}. The default for
|
|
+@var{char} is the TAB character without @option{-w} and @samp{no
|
|
+character} with @option{-w}. Without @option{-s} the default separator
|
|
+@samp{space} is set. @option{-s[char]} turns off line truncation of all
|
|
+three column options (@option{-COLUMN}|@option{-a -COLUMN}|@option{-m}) unless
|
|
+@option{-w} is set. This is a @acronym{POSIX}-compliant formulation.
|
|
+
|
|
+
|
|
+@item -S@var{string}
|
|
+@itemx --sep-string[=@var{string}]
|
|
+@opindex -S
|
|
+@opindex --sep-string
|
|
+Use @var{string} to separate output columns. The @option{-S} option doesn't
|
|
+affect the @option{-W/-w} option, unlike the @option{-s} option which does. It
|
|
+does not affect line truncation or column alignment.
|
|
+Without @option{-S}, and with @option{-J}, @command{pr} uses the default output
|
|
+separator, TAB@.
|
|
+Without @option{-S} or @option{-J}, @command{pr} uses a @samp{space}
|
|
+(same as @option{-S"@w{ }"}). @option{--sep-string} with no
|
|
+@samp{=@var{string}} is equivalent to @option{--sep-string=""}.
|
|
+
|
|
+@item -t
|
|
+@itemx --omit-header
|
|
+@opindex -t
|
|
+@opindex --omit-header
|
|
+Do not print the usual header [and footer] on each page, and do not fill
|
|
+out the bottom of pages (with blank lines or a form feed). No page
|
|
+structure is produced, but form feeds set in the input files are retained.
|
|
+The predefined pagination is not changed. @option{-t} or @option{-T} may be
|
|
+useful together with other options; e.g.: @option{-t -e4}, expand TAB characters
|
|
+in the input file to 4 spaces but don't make any other changes. Use of
|
|
+@option{-t} overrides @option{-h}.
|
|
+
|
|
+@item -T
|
|
+@itemx --omit-pagination
|
|
+@opindex -T
|
|
+@opindex --omit-pagination
|
|
+Do not print header [and footer]. In addition eliminate all form feeds
|
|
+set in the input files.
|
|
+
|
|
+@item -v
|
|
+@itemx --show-nonprinting
|
|
+@opindex -v
|
|
+@opindex --show-nonprinting
|
|
+Print nonprinting characters in octal backslash notation.
|
|
+
|
|
+@item -w @var{page_width}
|
|
+@itemx --width=@var{page_width}
|
|
+@opindex -w
|
|
+@opindex --width
|
|
+Set page width to @var{page_width} characters for multiple text-column
|
|
+output only (default for @var{page_width} is 72). @option{-s[CHAR]} turns
|
|
+off the default page width and any line truncation and column alignment.
|
|
+Lines of full length are merged, regardless of the column options
|
|
+set. No @var{page_width} setting is possible with single column output.
|
|
+A @acronym{POSIX}-compliant formulation.
|
|
+
|
|
+@item -W @var{page_width}
|
|
+@itemx --page_width=@var{page_width}
|
|
+@opindex -W
|
|
+@opindex --page_width
|
|
+Set the page width to @var{page_width} characters. That's valid with and
|
|
+without a column option. Text lines are truncated, unless @option{-J}
|
|
+is used. Together with one of the three column options
|
|
+(@option{-@var{column}}, @option{-a -@var{column}} or @option{-m}) column
|
|
+alignment is always used. The separator options @option{-S} or @option{-s}
|
|
+don't affect the @option{-W} option. Default is 72 characters. Without
|
|
+@option{-W @var{page_width}} and without any of the column options NO line
|
|
+truncation is used (defined to keep downward compatibility and to meet
|
|
+most frequent tasks). That's equivalent to @option{-W 72 -J}. The header
|
|
+line is never truncated.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node fold invocation
|
|
+@section @command{fold}: Wrap input lines to fit in specified width
|
|
+
|
|
+@pindex fold
|
|
+@cindex wrapping long input lines
|
|
+@cindex folding long input lines
|
|
+
|
|
+@command{fold} writes each @var{file} (@option{-} means standard input), or
|
|
+standard input if none are given, to standard output, breaking long
|
|
+lines. Synopsis:
|
|
+
|
|
+@example
|
|
+fold [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+By default, @command{fold} breaks lines wider than 80 columns. The output
|
|
+is split into as many lines as necessary.
|
|
+
|
|
+@cindex screen columns
|
|
+@command{fold} counts screen columns by default; thus, a tab may count more
|
|
+than one column, backspace decreases the column count, and carriage
|
|
+return sets the column to zero.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -b
|
|
+@itemx --bytes
|
|
+@opindex -b
|
|
+@opindex --bytes
|
|
+Count bytes rather than columns, so that tabs, backspaces, and carriage
|
|
+returns are each counted as taking up one column, just like other
|
|
+characters.
|
|
+
|
|
+@item -s
|
|
+@itemx --spaces
|
|
+@opindex -s
|
|
+@opindex --spaces
|
|
+Break at word boundaries: the line is broken after the last blank before
|
|
+the maximum line length. If the line contains no such blanks, the line
|
|
+is broken at the maximum line length as usual.
|
|
+
|
|
+@item -w @var{width}
|
|
+@itemx --width=@var{width}
|
|
+@opindex -w
|
|
+@opindex --width
|
|
+Use a maximum line length of @var{width} columns instead of 80.
|
|
+
|
|
+For compatibility @command{fold} supports an obsolete option syntax
|
|
+@option{-@var{width}}. New scripts should use @option{-w @var{width}}
|
|
+instead.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node Output of parts of files
|
|
+@chapter Output of parts of files
|
|
+
|
|
+@cindex output of parts of files
|
|
+@cindex parts of files, output of
|
|
+
|
|
+These commands output pieces of the input.
|
|
+
|
|
+@menu
|
|
+* 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.
|
|
+@end menu
|
|
+
|
|
+@node head invocation
|
|
+@section @command{head}: Output the first part of files
|
|
+
|
|
+@pindex head
|
|
+@cindex initial part of files, outputting
|
|
+@cindex first part of files, outputting
|
|
+
|
|
+@command{head} prints the first part (10 lines by default) of each
|
|
+@var{file}; it reads from standard input if no files are given or
|
|
+when given a @var{file} of @option{-}. Synopsis:
|
|
+
|
|
+@example
|
|
+head [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+If more than one @var{file} is specified, @command{head} prints a
|
|
+one-line header consisting of:
|
|
+
|
|
+@example
|
|
+==> @var{file name} <==
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+before the output for each @var{file}.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -c @var{k}
|
|
+@itemx --bytes=@var{k}
|
|
+@opindex -c
|
|
+@opindex --bytes
|
|
+Print the first @var{k} bytes, instead of initial lines.
|
|
+However, if @var{k} starts with a @samp{-},
|
|
+print all but the last @var{k} bytes of each file.
|
|
+@multiplierSuffixes{k}
|
|
+
|
|
+@itemx -n @var{k}
|
|
+@itemx --lines=@var{k}
|
|
+@opindex -n
|
|
+@opindex --lines
|
|
+Output the first @var{k} lines.
|
|
+However, if @var{k} starts with a @samp{-},
|
|
+print all but the last @var{k} lines of each file.
|
|
+Size multiplier suffixes are the same as with the @option{-c} option.
|
|
+
|
|
+@item -q
|
|
+@itemx --quiet
|
|
+@itemx --silent
|
|
+@opindex -q
|
|
+@opindex --quiet
|
|
+@opindex --silent
|
|
+Never print file name headers.
|
|
+
|
|
+@item -v
|
|
+@itemx --verbose
|
|
+@opindex -v
|
|
+@opindex --verbose
|
|
+Always print file name headers.
|
|
+
|
|
+@end table
|
|
+
|
|
+For compatibility @command{head} also supports an obsolete option syntax
|
|
+@option{-@var{count}@var{options}}, which is recognized only if it is
|
|
+specified first. @var{count} is a decimal number optionally followed
|
|
+by a size letter (@samp{b}, @samp{k}, @samp{m}) as in @option{-c}, or
|
|
+@samp{l} to mean count by lines, or other option letters (@samp{cqv}).
|
|
+Scripts intended for standard hosts should use @option{-c @var{count}}
|
|
+or @option{-n @var{count}} instead. If your script must also run on
|
|
+hosts that support only the obsolete syntax, it is usually simpler to
|
|
+avoid @command{head}, e.g., by using @samp{sed 5q} instead of
|
|
+@samp{head -5}.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node tail invocation
|
|
+@section @command{tail}: Output the last part of files
|
|
+
|
|
+@pindex tail
|
|
+@cindex last part of files, outputting
|
|
+
|
|
+@command{tail} prints the last part (10 lines by default) of each
|
|
+@var{file}; it reads from standard input if no files are given or
|
|
+when given a @var{file} of @samp{-}. Synopsis:
|
|
+
|
|
+@example
|
|
+tail [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+If more than one @var{file} is specified, @command{tail} prints a
|
|
+one-line header consisting of:
|
|
+
|
|
+@example
|
|
+==> @var{file name} <==
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+before the output for each @var{file}.
|
|
+
|
|
+@cindex BSD @command{tail}
|
|
+@sc{gnu} @command{tail} can output any amount of data (some other versions of
|
|
+@command{tail} cannot). It also has no @option{-r} option (print in
|
|
+reverse), since reversing a file is really a different job from printing
|
|
+the end of a file; BSD @command{tail} (which is the one with @option{-r}) can
|
|
+only reverse files that are at most as large as its buffer, which is
|
|
+typically 32 KiB@. A more reliable and versatile way to reverse files is
|
|
+the @sc{gnu} @command{tac} command.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -c @var{k}
|
|
+@itemx --bytes=@var{k}
|
|
+@opindex -c
|
|
+@opindex --bytes
|
|
+Output the last @var{k} bytes, instead of final lines.
|
|
+However, if @var{k} starts with a @samp{+}, start printing with the
|
|
+@var{k}th byte from the start of each file, instead of from the end.
|
|
+@multiplierSuffixes{k}
|
|
+
|
|
+@item -f
|
|
+@itemx --follow[=@var{how}]
|
|
+@opindex -f
|
|
+@opindex --follow
|
|
+@cindex growing files
|
|
+@vindex name @r{follow option}
|
|
+@vindex descriptor @r{follow option}
|
|
+Loop forever trying to read more characters at the end of the file,
|
|
+presumably because the file is growing.
|
|
+If more than one file is given, @command{tail} prints a header whenever it
|
|
+gets output from a different file, to indicate which file that output is
|
|
+from.
|
|
+
|
|
+There are two ways to specify how you'd like to track files with this option,
|
|
+but that difference is noticeable only when a followed file is removed or
|
|
+renamed.
|
|
+If you'd like to continue to track the end of a growing file even after
|
|
+it has been unlinked, use @option{--follow=descriptor}. This is the default
|
|
+behavior, but it is not useful if you're tracking a log file that may be
|
|
+rotated (removed or renamed, then reopened). In that case, use
|
|
+@option{--follow=name} to track the named file by reopening it periodically
|
|
+to see if it has been removed and recreated by some other program.
|
|
+
|
|
+No matter which method you use, if the tracked file is determined to have
|
|
+shrunk, @command{tail} prints a message saying the file has been truncated
|
|
+and resumes tracking the end of the file from the newly-determined endpoint.
|
|
+
|
|
+When a file is removed, @command{tail}'s behavior depends on whether it is
|
|
+following the name or the descriptor. When following by name, tail can
|
|
+detect that a file has been removed and gives a message to that effect,
|
|
+and if @option{--retry} has been specified it will continue checking
|
|
+periodically to see if the file reappears.
|
|
+When following a descriptor, tail does not detect that the file has
|
|
+been unlinked or renamed and issues no message; even though the file
|
|
+may no longer be accessible via its original name, it may still be
|
|
+growing.
|
|
+
|
|
+The option values @samp{descriptor} and @samp{name} may be specified only
|
|
+with the long form of the option, not with @option{-f}.
|
|
+
|
|
+The @option{-f} option is ignored if
|
|
+no @var{file} operand is specified and standard input is a FIFO or a pipe.
|
|
+Likewise, the @option{-f} option has no effect for any
|
|
+operand specified as @samp{-}, when standard input is a FIFO or a pipe.
|
|
+
|
|
+@item -F
|
|
+@opindex -F
|
|
+This option is the same as @option{--follow=name --retry}. That is, tail
|
|
+will attempt to reopen a file when it is removed. Should this fail, tail
|
|
+will keep trying until it becomes accessible again.
|
|
+
|
|
+@itemx --retry
|
|
+@opindex --retry
|
|
+This option is useful mainly when following by name (i.e., with
|
|
+@option{--follow=name}).
|
|
+Without this option, when tail encounters a file that doesn't
|
|
+exist or is otherwise inaccessible, it reports that fact and
|
|
+never checks it again.
|
|
+
|
|
+@itemx --sleep-interval=@var{number}
|
|
+@opindex --sleep-interval
|
|
+Change the number of seconds to wait between iterations (the default is 1.0).
|
|
+During one iteration, every specified file is checked to see if it has
|
|
+changed size.
|
|
+Historical implementations of @command{tail} have required that
|
|
+@var{number} be an integer. However, GNU @command{tail} accepts
|
|
+an arbitrary floating point number (using a period before any
|
|
+fractional digits).
|
|
+
|
|
+@itemx --pid=@var{pid}
|
|
+@opindex --pid
|
|
+When following by name or by descriptor, you may specify the process ID,
|
|
+@var{pid}, of the sole writer of all @var{file} arguments. Then, shortly
|
|
+after that process terminates, tail will also terminate. This will
|
|
+work properly only if the writer and the tailing process are running on
|
|
+the same machine. For example, to save the output of a build in a file
|
|
+and to watch the file grow, if you invoke @command{make} and @command{tail}
|
|
+like this then the tail process will stop when your build completes.
|
|
+Without this option, you would have had to kill the @code{tail -f}
|
|
+process yourself.
|
|
+
|
|
+@example
|
|
+$ make >& makerr & tail --pid=$! -f makerr
|
|
+@end example
|
|
+
|
|
+If you specify a @var{pid} that is not in use or that does not correspond
|
|
+to the process that is writing to the tailed files, then @command{tail}
|
|
+may terminate long before any @var{file}s stop growing or it may not
|
|
+terminate until long after the real writer has terminated.
|
|
+Note that @option{--pid} cannot be supported on some systems; @command{tail}
|
|
+will print a warning if this is the case.
|
|
+
|
|
+@itemx --max-unchanged-stats=@var{n}
|
|
+@opindex --max-unchanged-stats
|
|
+When tailing a file by name, if there have been @var{n} (default
|
|
+n=@value{DEFAULT_MAX_N_UNCHANGED_STATS_BETWEEN_OPENS}) consecutive
|
|
+iterations for which the file has not changed, then
|
|
+@code{open}/@code{fstat} the file to determine if that file name is
|
|
+still associated with the same device/inode-number pair as before.
|
|
+When following a log file that is rotated, this is approximately the
|
|
+number of seconds between when tail prints the last pre-rotation lines
|
|
+and when it prints the lines that have accumulated in the new log file.
|
|
+This option is meaningful only when following by name.
|
|
+
|
|
+@itemx -n @var{k}
|
|
+@itemx --lines=@var{k}
|
|
+@opindex -n
|
|
+@opindex --lines
|
|
+Output the last @var{k} lines.
|
|
+However, if @var{k} starts with a @samp{+}, start printing with the
|
|
+@var{k}th line from the start of each file, instead of from the end.
|
|
+Size multiplier suffixes are the same as with the @option{-c} option.
|
|
+
|
|
+@item -q
|
|
+@itemx --quiet
|
|
+@itemx --silent
|
|
+@opindex -q
|
|
+@opindex --quiet
|
|
+@opindex --silent
|
|
+Never print file name headers.
|
|
+
|
|
+@item -v
|
|
+@itemx --verbose
|
|
+@opindex -v
|
|
+@opindex --verbose
|
|
+Always print file name headers.
|
|
+
|
|
+@end table
|
|
+
|
|
+For compatibility @command{tail} also supports an obsolete usage
|
|
+@samp{tail -[@var{count}][bcl][f] [@var{file}]}, which is recognized
|
|
+only if it does not conflict with the usage described
|
|
+above. This obsolete form uses exactly one option and at most one
|
|
+file. In the option, @var{count} is an optional decimal number optionally
|
|
+followed by a size letter (@samp{b}, @samp{c}, @samp{l}) to mean count
|
|
+by 512-byte blocks, bytes, or lines, optionally followed by @samp{f}
|
|
+which has the same meaning as @option{-f}.
|
|
+
|
|
+@vindex _POSIX2_VERSION
|
|
+On older systems, the leading @samp{-} can be replaced by @samp{+} in
|
|
+the obsolete option syntax with the same meaning as in counts, and
|
|
+obsolete usage overrides normal usage when the two conflict.
|
|
+This obsolete behavior can be enabled or disabled with the
|
|
+@env{_POSIX2_VERSION} environment variable (@pxref{Standards
|
|
+conformance}).
|
|
+
|
|
+Scripts intended for use on standard hosts should avoid obsolete
|
|
+syntax and should use @option{-c @var{count}[b]}, @option{-n
|
|
+@var{count}}, and/or @option{-f} instead. If your script must also
|
|
+run on hosts that support only the obsolete syntax, you can often
|
|
+rewrite it to avoid problematic usages, e.g., by using @samp{sed -n
|
|
+'$p'} rather than @samp{tail -1}. If that's not possible, the script
|
|
+can use a test like @samp{if tail -c +1 </dev/null >/dev/null 2>&1;
|
|
+then @dots{}} to decide which syntax to use.
|
|
+
|
|
+Even if your script assumes the standard behavior, you should still
|
|
+beware usages whose behaviors differ depending on the @acronym{POSIX}
|
|
+version. For example, avoid @samp{tail - main.c}, since it might be
|
|
+interpreted as either @samp{tail main.c} or as @samp{tail -- -
|
|
+main.c}; avoid @samp{tail -c 4}, since it might mean either @samp{tail
|
|
+-c4} or @samp{tail -c 10 4}; and avoid @samp{tail +4}, since it might
|
|
+mean either @samp{tail ./+4} or @samp{tail -n +4}.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node split invocation
|
|
+@section @command{split}: Split a file into fixed-size pieces
|
|
+
|
|
+@pindex split
|
|
+@cindex splitting a file into pieces
|
|
+@cindex pieces, splitting a file into
|
|
+
|
|
+@command{split} creates output files containing consecutive sections of
|
|
+@var{input} (standard input if none is given or @var{input} is
|
|
+@samp{-}). Synopsis:
|
|
+
|
|
+@example
|
|
+split [@var{option}] [@var{input} [@var{prefix}]]
|
|
+@end example
|
|
+
|
|
+By default, @command{split} puts 1000 lines of @var{input} (or whatever is
|
|
+left over for the last section), into each output file.
|
|
+
|
|
+@cindex output file name prefix
|
|
+The output files' names consist of @var{prefix} (@samp{x} by default)
|
|
+followed by a group of characters (@samp{aa}, @samp{ab}, @dots{} by
|
|
+default), such that concatenating the output files in traditional
|
|
+sorted order by file name produces
|
|
+the original input file. If the output file names are exhausted,
|
|
+@command{split} reports an error without deleting the output files
|
|
+that it did create.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -l @var{lines}
|
|
+@itemx --lines=@var{lines}
|
|
+@opindex -l
|
|
+@opindex --lines
|
|
+Put @var{lines} lines of @var{input} into each output file.
|
|
+
|
|
+For compatibility @command{split} also supports an obsolete
|
|
+option syntax @option{-@var{lines}}. New scripts should use @option{-l
|
|
+@var{lines}} instead.
|
|
+
|
|
+@item -b @var{size}
|
|
+@itemx --bytes=@var{size}
|
|
+@opindex -b
|
|
+@opindex --bytes
|
|
+Put @var{size} bytes of @var{input} into each output file.
|
|
+@multiplierSuffixes{size}
|
|
+
|
|
+@item -C @var{size}
|
|
+@itemx --line-bytes=@var{size}
|
|
+@opindex -C
|
|
+@opindex --line-bytes
|
|
+Put into each output file as many complete lines of @var{input} as
|
|
+possible without exceeding @var{size} bytes. Individual lines longer than
|
|
+@var{size} bytes are broken into multiple files.
|
|
+@var{size} has the same format as for the @option{--bytes} option.
|
|
+
|
|
+@item -a @var{length}
|
|
+@itemx --suffix-length=@var{length}
|
|
+@opindex -a
|
|
+@opindex --suffix-length
|
|
+Use suffixes of length @var{length}. The default @var{length} is 2.
|
|
+
|
|
+@item -d
|
|
+@itemx --numeric-suffixes
|
|
+@opindex -d
|
|
+@opindex --numeric-suffixes
|
|
+Use digits in suffixes rather than lower-case letters.
|
|
+
|
|
+@itemx --verbose
|
|
+@opindex --verbose
|
|
+Write a diagnostic just before each output file is opened.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node csplit invocation
|
|
+@section @command{csplit}: Split a file into context-determined pieces
|
|
+
|
|
+@pindex csplit
|
|
+@cindex context splitting
|
|
+@cindex splitting a file into pieces by context
|
|
+
|
|
+@command{csplit} creates zero or more output files containing sections of
|
|
+@var{input} (standard input if @var{input} is @samp{-}). Synopsis:
|
|
+
|
|
+@example
|
|
+csplit [@var{option}]@dots{} @var{input} @var{pattern}@dots{}
|
|
+@end example
|
|
+
|
|
+The contents of the output files are determined by the @var{pattern}
|
|
+arguments, as detailed below. An error occurs if a @var{pattern}
|
|
+argument refers to a nonexistent line of the input file (e.g., if no
|
|
+remaining line matches a given regular expression). After every
|
|
+@var{pattern} has been matched, any remaining input is copied into one
|
|
+last output file.
|
|
+
|
|
+By default, @command{csplit} prints the number of bytes written to each
|
|
+output file after it has been created.
|
|
+
|
|
+The types of pattern arguments are:
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item @var{n}
|
|
+Create an output file containing the input up to but not including line
|
|
+@var{n} (a positive integer). If followed by a repeat count, also
|
|
+create an output file containing the next @var{n} lines of the input
|
|
+file once for each repeat.
|
|
+
|
|
+@item /@var{regexp}/[@var{offset}]
|
|
+Create an output file containing the current line up to (but not
|
|
+including) the next line of the input file that contains a match for
|
|
+@var{regexp}. The optional @var{offset} is an integer.
|
|
+If it is given, the input up to (but not including) the
|
|
+matching line plus or minus @var{offset} is put into the output file,
|
|
+and the line after that begins the next section of input.
|
|
+
|
|
+@item %@var{regexp}%[@var{offset}]
|
|
+Like the previous type, except that it does not create an output
|
|
+file, so that section of the input file is effectively ignored.
|
|
+
|
|
+@item @{@var{repeat-count}@}
|
|
+Repeat the previous pattern @var{repeat-count} additional
|
|
+times. The @var{repeat-count} can either be a positive integer or an
|
|
+asterisk, meaning repeat as many times as necessary until the input is
|
|
+exhausted.
|
|
+
|
|
+@end table
|
|
+
|
|
+The output files' names consist of a prefix (@samp{xx} by default)
|
|
+followed by a suffix. By default, the suffix is an ascending sequence
|
|
+of two-digit decimal numbers from @samp{00} to @samp{99}. In any case,
|
|
+concatenating the output files in sorted order by file name produces the
|
|
+original input file.
|
|
+
|
|
+By default, if @command{csplit} encounters an error or receives a hangup,
|
|
+interrupt, quit, or terminate signal, it removes any output files
|
|
+that it has created so far before it exits.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -f @var{prefix}
|
|
+@itemx --prefix=@var{prefix}
|
|
+@opindex -f
|
|
+@opindex --prefix
|
|
+@cindex output file name prefix
|
|
+Use @var{prefix} as the output file name prefix.
|
|
+
|
|
+@item -b @var{suffix}
|
|
+@itemx --suffix=@var{suffix}
|
|
+@opindex -b
|
|
+@opindex --suffix
|
|
+@cindex output file name suffix
|
|
+Use @var{suffix} as the output file name suffix. When this option is
|
|
+specified, the suffix string must include exactly one
|
|
+@code{printf(3)}-style conversion specification, possibly including
|
|
+format specification flags, a field width, a precision specifications,
|
|
+or all of these kinds of modifiers. The format letter must convert a
|
|
+binary integer argument to readable form; thus, only @samp{d}, @samp{i},
|
|
+@samp{u}, @samp{o}, @samp{x}, and @samp{X} conversions are allowed. The
|
|
+entire @var{suffix} is given (with the current output file number) to
|
|
+@code{sprintf(3)} to form the file name suffixes for each of the
|
|
+individual output files in turn. If this option is used, the
|
|
+@option{--digits} option is ignored.
|
|
+
|
|
+@item -n @var{digits}
|
|
+@itemx --digits=@var{digits}
|
|
+@opindex -n
|
|
+@opindex --digits
|
|
+Use output file names containing numbers that are @var{digits} digits
|
|
+long instead of the default 2.
|
|
+
|
|
+@item -k
|
|
+@itemx --keep-files
|
|
+@opindex -k
|
|
+@opindex --keep-files
|
|
+Do not remove output files when errors are encountered.
|
|
+
|
|
+@item -z
|
|
+@itemx --elide-empty-files
|
|
+@opindex -z
|
|
+@opindex --elide-empty-files
|
|
+Suppress the generation of zero-length output files. (In cases where
|
|
+the section delimiters of the input file are supposed to mark the first
|
|
+lines of each of the sections, the first output file will generally be a
|
|
+zero-length file unless you use this option.) The output file sequence
|
|
+numbers always run consecutively starting from 0, even when this option
|
|
+is specified.
|
|
+
|
|
+@item -s
|
|
+@itemx -q
|
|
+@itemx --silent
|
|
+@itemx --quiet
|
|
+@opindex -s
|
|
+@opindex -q
|
|
+@opindex --silent
|
|
+@opindex --quiet
|
|
+Do not print counts of output file sizes.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+Here is an example of its usage.
|
|
+First, create an empty directory for the exercise,
|
|
+and cd into it:
|
|
+
|
|
+@example
|
|
+$ mkdir d && cd d
|
|
+@end example
|
|
+
|
|
+Now, split the sequence of 1..14 on lines that end with 0 or 5:
|
|
+
|
|
+@example
|
|
+$ seq 14 | csplit - '/[05]$/' '@{*@}'
|
|
+8
|
|
+10
|
|
+15
|
|
+@end example
|
|
+
|
|
+Each number printed above is the size of an output
|
|
+file that csplit has just created.
|
|
+List the names of those output files:
|
|
+
|
|
+@example
|
|
+$ ls
|
|
+xx00 xx01 xx02
|
|
+@end example
|
|
+
|
|
+Use @command{head} to show their contents:
|
|
+
|
|
+@example
|
|
+$ head xx*
|
|
+==> xx00 <==
|
|
+1
|
|
+2
|
|
+3
|
|
+4
|
|
+
|
|
+==> xx01 <==
|
|
+5
|
|
+6
|
|
+7
|
|
+8
|
|
+9
|
|
+
|
|
+==> xx02 <==
|
|
+10
|
|
+11
|
|
+12
|
|
+13
|
|
+14
|
|
+@end example
|
|
+
|
|
+@node Summarizing files
|
|
+@chapter Summarizing files
|
|
+
|
|
+@cindex summarizing files
|
|
+
|
|
+These commands generate just a few numbers representing entire
|
|
+contents of files.
|
|
+
|
|
+@menu
|
|
+* 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.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node wc invocation
|
|
+@section @command{wc}: Print newline, word, and byte counts
|
|
+
|
|
+@pindex wc
|
|
+@cindex byte count
|
|
+@cindex character count
|
|
+@cindex word count
|
|
+@cindex line count
|
|
+
|
|
+@command{wc} counts the number of bytes, characters, whitespace-separated
|
|
+words, and newlines in each given @var{file}, or standard input if none
|
|
+are given or for a @var{file} of @samp{-}. Synopsis:
|
|
+
|
|
+@example
|
|
+wc [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+@cindex total counts
|
|
+@command{wc} prints one line of counts for each file, and if the file was
|
|
+given as an argument, it prints the file name following the counts. If
|
|
+more than one @var{file} is given, @command{wc} prints a final line
|
|
+containing the cumulative counts, with the file name @file{total}. The
|
|
+counts are printed in this order: newlines, words, characters, bytes,
|
|
+maximum line length.
|
|
+Each count is printed right-justified in a field with at least one
|
|
+space between fields so that the numbers and file names normally line
|
|
+up nicely in columns. The width of the count fields varies depending
|
|
+on the inputs, so you should not depend on a particular field width.
|
|
+However, as a @acronym{GNU} extension, if only one count is printed,
|
|
+it is guaranteed to be printed without leading spaces.
|
|
+
|
|
+By default, @command{wc} prints three counts: the newline, words, and byte
|
|
+counts. Options can specify that only certain counts be printed.
|
|
+Options do not undo others previously given, so
|
|
+
|
|
+@example
|
|
+wc --bytes --words
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+prints both the byte counts and the word counts.
|
|
+
|
|
+With the @option{--max-line-length} option, @command{wc} prints the length
|
|
+of the longest line per file, and if there is more than one file it
|
|
+prints the maximum (not the sum) of those lengths. The line lengths here
|
|
+are measured in screen columns, according to the current locale and
|
|
+assuming tab positions in every 8th column.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -c
|
|
+@itemx --bytes
|
|
+@opindex -c
|
|
+@opindex --bytes
|
|
+Print only the byte counts.
|
|
+
|
|
+@item -m
|
|
+@itemx --chars
|
|
+@opindex -m
|
|
+@opindex --chars
|
|
+Print only the character counts.
|
|
+
|
|
+@item -w
|
|
+@itemx --words
|
|
+@opindex -w
|
|
+@opindex --words
|
|
+Print only the word counts.
|
|
+
|
|
+@item -l
|
|
+@itemx --lines
|
|
+@opindex -l
|
|
+@opindex --lines
|
|
+Print only the newline counts.
|
|
+
|
|
+@item -L
|
|
+@itemx --max-line-length
|
|
+@opindex -L
|
|
+@opindex --max-line-length
|
|
+Print only the maximum line lengths.
|
|
+
|
|
+@macro filesZeroFromOption{cmd,withTotalOption,subListOutput}
|
|
+@itemx --files0-from=@var{file}
|
|
+@opindex --files0-from=@var{file}
|
|
+@c This is commented out to avoid a texi2dvi failure.
|
|
+@c texi2dvi (GNU Texinfo 4.11) 1.104
|
|
+@c @cindex including files from @command{\cmd\}
|
|
+Disallow processing files named on the command line, and instead process
|
|
+those named in file @var{file}; each name being terminated by a zero byte
|
|
+(@acronym{ASCII} @sc{nul}).
|
|
+This is useful \withTotalOption\
|
|
+when the list of file names is so long that it may exceed a command line
|
|
+length limitation.
|
|
+In such cases, running @command{\cmd\} via @command{xargs} is undesirable
|
|
+because it splits the list into pieces and makes @command{\cmd\} print
|
|
+\subListOutput\ for each sublist rather than for the entire list.
|
|
+One way to produce a list of @acronym{ASCII} @sc{nul} terminated file names is with @sc{gnu}
|
|
+@command{find}, using its @option{-print0} predicate.
|
|
+If @var{file} is @samp{-} then the @acronym{ASCII} @sc{nul} terminated file names
|
|
+are read from standard input.
|
|
+@end macro
|
|
+@filesZeroFromOption{wc,,a total}
|
|
+
|
|
+For example, to find the length of the longest line in any @file{.c} or
|
|
+@file{.h} file in the current hierarchy, do this:
|
|
+
|
|
+@example
|
|
+find . -name '*.[ch]' -print0 |
|
|
+ wc -L --files0-from=- | tail -n1
|
|
+@end example
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node sum invocation
|
|
+@section @command{sum}: Print checksum and block counts
|
|
+
|
|
+@pindex sum
|
|
+@cindex 16-bit checksum
|
|
+@cindex checksum, 16-bit
|
|
+
|
|
+@command{sum} computes a 16-bit checksum for each given @var{file}, or
|
|
+standard input if none are given or for a @var{file} of @samp{-}. Synopsis:
|
|
+
|
|
+@example
|
|
+sum [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+@command{sum} prints the checksum for each @var{file} followed by the
|
|
+number of blocks in the file (rounded up). If more than one @var{file}
|
|
+is given, file names are also printed (by default). (With the
|
|
+@option{--sysv} option, corresponding file names are printed when there is
|
|
+at least one file argument.)
|
|
+
|
|
+By default, @sc{gnu} @command{sum} computes checksums using an algorithm
|
|
+compatible with BSD @command{sum} and prints file sizes in units of
|
|
+1024-byte blocks.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -r
|
|
+@opindex -r
|
|
+@cindex BSD @command{sum}
|
|
+Use the default (BSD compatible) algorithm. This option is included for
|
|
+compatibility with the System V @command{sum}. Unless @option{-s} was also
|
|
+given, it has no effect.
|
|
+
|
|
+@item -s
|
|
+@itemx --sysv
|
|
+@opindex -s
|
|
+@opindex --sysv
|
|
+@cindex System V @command{sum}
|
|
+Compute checksums using an algorithm compatible with System V
|
|
+@command{sum}'s default, and print file sizes in units of 512-byte blocks.
|
|
+
|
|
+@end table
|
|
+
|
|
+@command{sum} is provided for compatibility; the @command{cksum} program (see
|
|
+next section) is preferable in new applications.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node cksum invocation
|
|
+@section @command{cksum}: Print CRC checksum and byte counts
|
|
+
|
|
+@pindex cksum
|
|
+@cindex cyclic redundancy check
|
|
+@cindex CRC checksum
|
|
+
|
|
+@command{cksum} computes a cyclic redundancy check (CRC) checksum for each
|
|
+given @var{file}, or standard input if none are given or for a
|
|
+@var{file} of @samp{-}. Synopsis:
|
|
+
|
|
+@example
|
|
+cksum [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+@command{cksum} prints the CRC checksum for each file along with the number
|
|
+of bytes in the file, and the file name unless no arguments were given.
|
|
+
|
|
+@command{cksum} is typically used to ensure that files
|
|
+transferred by unreliable means (e.g., netnews) have not been corrupted,
|
|
+by comparing the @command{cksum} output for the received files with the
|
|
+@command{cksum} output for the original files (typically given in the
|
|
+distribution).
|
|
+
|
|
+The CRC algorithm is specified by the @acronym{POSIX} standard. It is not
|
|
+compatible with the BSD or System V @command{sum} algorithms (see the
|
|
+previous section); it is more robust.
|
|
+
|
|
+The only options are @option{--help} and @option{--version}. @xref{Common
|
|
+options}.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node md5sum invocation
|
|
+@section @command{md5sum}: Print or check MD5 digests
|
|
+
|
|
+@pindex md5sum
|
|
+@cindex MD5
|
|
+@cindex 128-bit checksum
|
|
+@cindex checksum, 128-bit
|
|
+@cindex fingerprint, 128-bit
|
|
+@cindex message-digest, 128-bit
|
|
+
|
|
+@command{md5sum} computes a 128-bit checksum (or @dfn{fingerprint} or
|
|
+@dfn{message-digest}) for each specified @var{file}.
|
|
+
|
|
+Note: The MD5 digest is more reliable than a simple CRC (provided by
|
|
+the @command{cksum} command) for detecting accidental file corruption,
|
|
+as the chances of accidentally having two files with identical MD5
|
|
+are vanishingly small. However, it should not be considered truly
|
|
+secure against malicious tampering: although finding a file with a
|
|
+given MD5 fingerprint, or modifying a file so as to retain its MD5 are
|
|
+considered infeasible at the moment, it is known how to produce
|
|
+different files with identical MD5 (a ``collision''), something which
|
|
+can be a security issue in certain contexts. For more secure hashes,
|
|
+consider using SHA-1 or SHA-2. @xref{sha1sum invocation}, and
|
|
+@ref{sha2 utilities}.
|
|
+
|
|
+If a @var{file} is specified as @samp{-} or if no files are given
|
|
+@command{md5sum} computes the checksum for the standard input.
|
|
+@command{md5sum} can also determine whether a file and checksum are
|
|
+consistent. Synopsis:
|
|
+
|
|
+@example
|
|
+md5sum [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+For each @var{file}, @samp{md5sum} outputs the MD5 checksum, a flag
|
|
+indicating a binary or text input file, and the file name.
|
|
+If @var{file} contains a backslash or newline, the
|
|
+line is started with a backslash, and each problematic character in
|
|
+the file name is escaped with a backslash, making the output
|
|
+unambiguous even in the presence of arbitrary file names.
|
|
+If @var{file} is omitted or specified as @samp{-}, standard input is read.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -b
|
|
+@itemx --binary
|
|
+@opindex -b
|
|
+@opindex --binary
|
|
+@cindex binary input files
|
|
+Treat each input file as binary, by reading it in binary mode and
|
|
+outputting a @samp{*} flag. This is the inverse of @option{--text}.
|
|
+On systems like @acronym{GNU} that do not distinguish between binary
|
|
+and text files, this option merely flags each input file as binary:
|
|
+the MD5 checksum is unaffected. This option is the default on systems
|
|
+like MS-DOS that distinguish between binary and text files, except
|
|
+for reading standard input when standard input is a terminal.
|
|
+
|
|
+@item -c
|
|
+@itemx --check
|
|
+Read file names and checksum information (not data) from each
|
|
+@var{file} (or from stdin if no @var{file} was specified) and report
|
|
+whether the checksums match the contents of the named files.
|
|
+The input to this mode of @command{md5sum} is usually the output of
|
|
+a prior, checksum-generating run of @samp{md5sum}.
|
|
+Each valid line of input consists of an MD5 checksum, a binary/text
|
|
+flag, and then a file name.
|
|
+Binary files are marked with @samp{*}, text with @samp{ }.
|
|
+For each such line, @command{md5sum} reads the named file and computes its
|
|
+MD5 checksum. Then, if the computed message digest does not match the
|
|
+one on the line with the file name, the file is noted as having
|
|
+failed the test. Otherwise, the file passes the test.
|
|
+By default, for each valid line, one line is written to standard
|
|
+output indicating whether the named file passed the test.
|
|
+After all checks have been performed, if there were any failures,
|
|
+a warning is issued to standard error.
|
|
+Use the @option{--status} option to inhibit that output.
|
|
+If any listed file cannot be opened or read, if any valid line has
|
|
+an MD5 checksum inconsistent with the associated file, or if no valid
|
|
+line is found, @command{md5sum} exits with nonzero status. Otherwise,
|
|
+it exits successfully.
|
|
+
|
|
+@itemx --quiet
|
|
+@opindex --quiet
|
|
+@cindex verifying MD5 checksums
|
|
+This option is useful only when verifying checksums.
|
|
+When verifying checksums, don't generate an 'OK' message per successfully
|
|
+checked file. Files that fail the verification are reported in the
|
|
+default one-line-per-file format. If there is any checksum mismatch,
|
|
+print a warning summarizing the failures to standard error.
|
|
+
|
|
+@itemx --status
|
|
+@opindex --status
|
|
+@cindex verifying MD5 checksums
|
|
+This option is useful only when verifying checksums.
|
|
+When verifying checksums, don't generate the default one-line-per-file
|
|
+diagnostic and don't output the warning summarizing any failures.
|
|
+Failures to open or read a file still evoke individual diagnostics to
|
|
+standard error.
|
|
+If all listed files are readable and are consistent with the associated
|
|
+MD5 checksums, exit successfully. Otherwise exit with a status code
|
|
+indicating there was a failure.
|
|
+
|
|
+@item -t
|
|
+@itemx --text
|
|
+@opindex -t
|
|
+@opindex --text
|
|
+@cindex text input files
|
|
+Treat each input file as text, by reading it in text mode and
|
|
+outputting a @samp{ } flag. This is the inverse of @option{--binary}.
|
|
+This option is the default on systems like @acronym{GNU} that do not
|
|
+distinguish between binary and text files. On other systems, it is
|
|
+the default for reading standard input when standard input is a
|
|
+terminal.
|
|
+
|
|
+@item -w
|
|
+@itemx --warn
|
|
+@opindex -w
|
|
+@opindex --warn
|
|
+@cindex verifying MD5 checksums
|
|
+When verifying checksums, warn about improperly formatted MD5 checksum lines.
|
|
+This option is useful only if all but a few lines in the checked input
|
|
+are valid.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node sha1sum invocation
|
|
+@section @command{sha1sum}: Print or check SHA-1 digests
|
|
+
|
|
+@pindex sha1sum
|
|
+@cindex SHA-1
|
|
+@cindex 160-bit checksum
|
|
+@cindex checksum, 160-bit
|
|
+@cindex fingerprint, 160-bit
|
|
+@cindex message-digest, 160-bit
|
|
+
|
|
+@command{sha1sum} computes a 160-bit checksum for each specified
|
|
+@var{file}. The usage and options of this command are precisely the
|
|
+same as for @command{md5sum}. @xref{md5sum invocation}.
|
|
+
|
|
+Note: The SHA-1 digest is more secure than MD5, and no collisions of
|
|
+it are known (different files having the same fingerprint). However,
|
|
+it is known that they can be produced with considerable, but not
|
|
+unreasonable, resources. For this reason, it is generally considered
|
|
+that SHA-1 should be gradually phased out in favor of the more secure
|
|
+SHA-2 hash algorithms. @xref{sha2 utilities}.
|
|
+
|
|
+
|
|
+@node sha2 utilities
|
|
+@section sha2 utilities: Print or check SHA-2 digests
|
|
+
|
|
+@pindex sha224sum
|
|
+@pindex sha256sum
|
|
+@pindex sha384sum
|
|
+@pindex sha512sum
|
|
+@cindex SHA-2
|
|
+@cindex 224-bit checksum
|
|
+@cindex 256-bit checksum
|
|
+@cindex 384-bit checksum
|
|
+@cindex 512-bit checksum
|
|
+@cindex checksum, 224-bit
|
|
+@cindex checksum, 256-bit
|
|
+@cindex checksum, 384-bit
|
|
+@cindex checksum, 512-bit
|
|
+@cindex fingerprint, 224-bit
|
|
+@cindex fingerprint, 256-bit
|
|
+@cindex fingerprint, 384-bit
|
|
+@cindex fingerprint, 512-bit
|
|
+@cindex message-digest, 224-bit
|
|
+@cindex message-digest, 256-bit
|
|
+@cindex message-digest, 384-bit
|
|
+@cindex message-digest, 512-bit
|
|
+
|
|
+The commands @command{sha224sum}, @command{sha256sum},
|
|
+@command{sha384sum} and @command{sha512sum} compute checksums of
|
|
+various lengths (respectively 224, 256, 384 and 512 bits),
|
|
+collectively known as the SHA-2 hashes. The usage and options of
|
|
+these commands are precisely the same as for @command{md5sum}.
|
|
+@xref{md5sum invocation}.
|
|
+
|
|
+Note: The SHA384 and SHA512 digests are considerably slower to
|
|
+compute, especially on 32-bit computers, than SHA224 or SHA256.
|
|
+
|
|
+
|
|
+@node Operating on sorted files
|
|
+@chapter Operating on sorted files
|
|
+
|
|
+@cindex operating on sorted files
|
|
+@cindex sorted files, operations on
|
|
+
|
|
+These commands work with (or produce) sorted files.
|
|
+
|
|
+@menu
|
|
+* 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.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node sort invocation
|
|
+@section @command{sort}: Sort text files
|
|
+
|
|
+@pindex sort
|
|
+@cindex sorting files
|
|
+
|
|
+@command{sort} sorts, merges, or compares all the lines from the given
|
|
+files, or standard input if none are given or for a @var{file} of
|
|
+@samp{-}. By default, @command{sort} writes the results to standard
|
|
+output. Synopsis:
|
|
+
|
|
+@example
|
|
+sort [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+@command{sort} has three modes of operation: sort (the default), merge,
|
|
+and check for sortedness. The following options change the operation
|
|
+mode:
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -c
|
|
+@itemx --check
|
|
+@itemx --check=diagnose-first
|
|
+@opindex -c
|
|
+@opindex --check
|
|
+@cindex checking for sortedness
|
|
+Check whether the given file is already sorted: if it is not all
|
|
+sorted, print a diagnostic containing the first out-of-order line and
|
|
+exit with a status of 1.
|
|
+Otherwise, exit successfully.
|
|
+At most one input file can be given.
|
|
+
|
|
+@item -C
|
|
+@itemx --check=quiet
|
|
+@itemx --check=silent
|
|
+@opindex -c
|
|
+@opindex --check
|
|
+@cindex checking for sortedness
|
|
+Exit successfully if the given file is already sorted, and
|
|
+exit with status 1 otherwise.
|
|
+At most one input file can be given.
|
|
+This is like @option{-c}, except it does not print a diagnostic.
|
|
+
|
|
+@item -m
|
|
+@itemx --merge
|
|
+@opindex -m
|
|
+@opindex --merge
|
|
+@cindex merging sorted files
|
|
+Merge the given files by sorting them as a group. Each input file must
|
|
+always be individually sorted. It always works to sort instead of
|
|
+merge; merging is provided because it is faster, in the case where it
|
|
+works.
|
|
+
|
|
+@end table
|
|
+
|
|
+@cindex sort stability
|
|
+@cindex sort's last-resort comparison
|
|
+A pair of lines is compared as follows:
|
|
+@command{sort} compares each pair of fields, in the
|
|
+order specified on the command line, according to the associated
|
|
+ordering options, until a difference is found or no fields are left.
|
|
+If no key fields are specified, @command{sort} uses a default key of
|
|
+the entire line. Finally, as a last resort when all keys compare
|
|
+equal, @command{sort} compares entire lines as if no ordering options
|
|
+other than @option{--reverse} (@option{-r}) were specified. The
|
|
+@option{--stable} (@option{-s}) option disables this @dfn{last-resort
|
|
+comparison} so that lines in which all fields compare equal are left
|
|
+in their original relative order. The @option{--unique}
|
|
+(@option{-u}) option also disables the last-resort comparison.
|
|
+
|
|
+@vindex LC_ALL
|
|
+@vindex LC_COLLATE
|
|
+Unless otherwise specified, all comparisons use the character collating
|
|
+sequence specified by the @env{LC_COLLATE} locale.@footnote{If you
|
|
+use a non-@acronym{POSIX} locale (e.g., by setting @env{LC_ALL}
|
|
+to @samp{en_US}), then @command{sort} may produce output that is sorted
|
|
+differently than you're accustomed to. In that case, set the @env{LC_ALL}
|
|
+environment variable to @samp{C}. Note that setting only @env{LC_COLLATE}
|
|
+has two problems. First, it is ineffective if @env{LC_ALL} is also set.
|
|
+Second, it has undefined behavior if @env{LC_CTYPE} (or @env{LANG}, if
|
|
+@env{LC_CTYPE} is unset) is set to an incompatible value. For example,
|
|
+you get undefined behavior if @env{LC_CTYPE} is @code{ja_JP.PCK} but
|
|
+@env{LC_COLLATE} is @code{en_US.UTF-8}.}
|
|
+
|
|
+@sc{gnu} @command{sort} (as specified for all @sc{gnu} utilities) has no
|
|
+limit on input line length or restrictions on bytes allowed within lines.
|
|
+In addition, if the final byte of an input file is not a newline, @sc{gnu}
|
|
+@command{sort} silently supplies one. A line's trailing newline is not
|
|
+part of the line for comparison purposes.
|
|
+
|
|
+@cindex exit status of @command{sort}
|
|
+Exit status:
|
|
+
|
|
+@display
|
|
+0 if no error occurred
|
|
+1 if invoked with @option{-c} or @option{-C} and the input is not sorted
|
|
+2 if an error occurred
|
|
+@end display
|
|
+
|
|
+@vindex TMPDIR
|
|
+If the environment variable @env{TMPDIR} is set, @command{sort} uses its
|
|
+value as the directory for temporary files instead of @file{/tmp}. The
|
|
+@option{--temporary-directory} (@option{-T}) option in turn overrides
|
|
+the environment variable.
|
|
+
|
|
+The following options affect the ordering of output lines. They may be
|
|
+specified globally or as part of a specific key field. If no key
|
|
+fields are specified, global options apply to comparison of entire
|
|
+lines; otherwise the global options are inherited by key fields that do
|
|
+not specify any special options of their own. In pre-@acronym{POSIX}
|
|
+versions of @command{sort}, global options affect only later key fields,
|
|
+so portable shell scripts should specify global options first.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -b
|
|
+@itemx --ignore-leading-blanks
|
|
+@opindex -b
|
|
+@opindex --ignore-leading-blanks
|
|
+@cindex blanks, ignoring leading
|
|
+@vindex LC_CTYPE
|
|
+Ignore leading blanks when finding sort keys in each line.
|
|
+By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
|
|
+can change this. Note blanks may be ignored by your locale's collating
|
|
+rules, but without this option they will be significant for character
|
|
+positions specified in keys with the @option{-k} option.
|
|
+
|
|
+@item -d
|
|
+@itemx --dictionary-order
|
|
+@opindex -d
|
|
+@opindex --dictionary-order
|
|
+@cindex dictionary order
|
|
+@cindex phone directory order
|
|
+@cindex telephone directory order
|
|
+@vindex LC_CTYPE
|
|
+Sort in @dfn{phone directory} order: ignore all characters except
|
|
+letters, digits and blanks when sorting.
|
|
+By default letters and digits are those of @acronym{ASCII} and a blank
|
|
+is a space or a tab, but the @env{LC_CTYPE} locale can change this.
|
|
+
|
|
+@item -f
|
|
+@itemx --ignore-case
|
|
+@opindex -f
|
|
+@opindex --ignore-case
|
|
+@cindex ignoring case
|
|
+@cindex case folding
|
|
+@vindex LC_CTYPE
|
|
+Fold lowercase characters into the equivalent uppercase characters when
|
|
+comparing so that, for example, @samp{b} and @samp{B} sort as equal.
|
|
+The @env{LC_CTYPE} locale determines character types.
|
|
+When used with @option{--unique} those lower case equivalent lines are
|
|
+thrown away. (There is currently no way to throw away the upper case
|
|
+equivalent instead. (Any @option{--reverse} given would only affect
|
|
+the final result, after the throwing away.))
|
|
+
|
|
+@item -g
|
|
+@itemx --general-numeric-sort
|
|
+@itemx --sort=general-numeric
|
|
+@opindex -g
|
|
+@opindex --general-numeric-sort
|
|
+@opindex --sort
|
|
+@cindex general numeric sort
|
|
+@vindex LC_NUMERIC
|
|
+Sort numerically, using the standard C function @code{strtod} to convert
|
|
+a prefix of each line to a double-precision floating point number.
|
|
+This allows floating point numbers to be specified in scientific notation,
|
|
+like @code{1.0e-34} and @code{10e100}.
|
|
+The @env{LC_NUMERIC} locale determines the decimal-point character.
|
|
+Do not report overflow, underflow, or conversion errors.
|
|
+Use the following collating sequence:
|
|
+
|
|
+@itemize @bullet
|
|
+@item
|
|
+Lines that do not start with numbers (all considered to be equal).
|
|
+@item
|
|
+NaNs (``Not a Number'' values, in IEEE floating point arithmetic)
|
|
+in a consistent but machine-dependent order.
|
|
+@item
|
|
+Minus infinity.
|
|
+@item
|
|
+Finite numbers in ascending numeric order (with @math{-0} and @math{+0} equal).
|
|
+@item
|
|
+Plus infinity.
|
|
+@end itemize
|
|
+
|
|
+Use this option only if there is no alternative; it is much slower than
|
|
+@option{--numeric-sort} (@option{-n}) and it can lose information when
|
|
+converting to floating point.
|
|
+
|
|
+@item -h
|
|
+@itemx --human-numeric-sort
|
|
+@itemx --sort=human-numeric
|
|
+@opindex -h
|
|
+@opindex --human-numeric-sort
|
|
+@opindex --sort
|
|
+@cindex human numeric sort
|
|
+@vindex LC_NUMERIC
|
|
+Sort numerically, as per the @option{--numeric-sort} option below, and in
|
|
+addition handle IEC or SI suffixes like MiB, MB etc (@ref{Block size}).
|
|
+Note a mixture of IEC and SI suffixes is not supported and will
|
|
+be flagged as an error. Also the numbers must be abbreviated uniformly.
|
|
+I.E. values with different precisions like 6000K and 5M will be sorted
|
|
+incorrectly.
|
|
+
|
|
+@item -i
|
|
+@itemx --ignore-nonprinting
|
|
+@opindex -i
|
|
+@opindex --ignore-nonprinting
|
|
+@cindex nonprinting characters, ignoring
|
|
+@cindex unprintable characters, ignoring
|
|
+@vindex LC_CTYPE
|
|
+Ignore nonprinting characters.
|
|
+The @env{LC_CTYPE} locale determines character types.
|
|
+This option has no effect if the stronger @option{--dictionary-order}
|
|
+(@option{-d}) option is also given.
|
|
+
|
|
+@item -M
|
|
+@itemx --month-sort
|
|
+@itemx --sort=month
|
|
+@opindex -M
|
|
+@opindex --month-sort
|
|
+@opindex --sort
|
|
+@cindex months, sorting by
|
|
+@vindex LC_TIME
|
|
+An initial string, consisting of any amount of blanks, followed
|
|
+by a month name abbreviation, is folded to UPPER case and
|
|
+compared in the order @samp{JAN} < @samp{FEB} < @dots{} < @samp{DEC}.
|
|
+Invalid names compare low to valid names. The @env{LC_TIME} locale
|
|
+category determines the month spellings.
|
|
+By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
|
|
+can change this.
|
|
+
|
|
+@item -n
|
|
+@itemx --numeric-sort
|
|
+@itemx --sort=numeric
|
|
+@opindex -n
|
|
+@opindex --numeric-sort
|
|
+@opindex --sort
|
|
+@cindex numeric sort
|
|
+@vindex LC_NUMERIC
|
|
+Sort numerically. The number begins each line and consists
|
|
+of optional blanks, an optional @samp{-} sign, and zero or more
|
|
+digits possibly separated by thousands separators, optionally followed
|
|
+by a decimal-point character and zero or more digits. An empty
|
|
+number is treated as @samp{0}. The @env{LC_NUMERIC}
|
|
+locale specifies the decimal-point character and thousands separator.
|
|
+By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
|
|
+can change this.
|
|
+
|
|
+Comparison is exact; there is no rounding error.
|
|
+
|
|
+Neither a leading @samp{+} nor exponential notation is recognized.
|
|
+To compare such strings numerically, use the
|
|
+@option{--general-numeric-sort} (@option{-g}) option.
|
|
+
|
|
+@item -V
|
|
+@itemx --version-sort
|
|
+@opindex -V
|
|
+@opindex --version-sort
|
|
+@cindex version number sort
|
|
+@vindex LC_NUMERIC
|
|
+Sort per @code{strverscmp(3)}. This is a normal string comparison, except
|
|
+that embedded decimal numbers are sorted by numeric value
|
|
+(see @option{--numeric-sort} above).
|
|
+
|
|
+@item -r
|
|
+@itemx --reverse
|
|
+@opindex -r
|
|
+@opindex --reverse
|
|
+@cindex reverse sorting
|
|
+Reverse the result of comparison, so that lines with greater key values
|
|
+appear earlier in the output instead of later.
|
|
+
|
|
+@item -R
|
|
+@itemx --random-sort
|
|
+@itemx --sort=random
|
|
+@opindex -R
|
|
+@opindex --random-sort
|
|
+@opindex --sort
|
|
+@cindex random sort
|
|
+Sort by hashing the input keys and then sorting the hash values.
|
|
+Choose the hash function at random, ensuring that it is free of
|
|
+collisions so that differing keys have differing hash values. This is
|
|
+like a random permutation of the inputs (@pxref{shuf invocation}),
|
|
+except that keys with the same value sort together.
|
|
+
|
|
+If multiple random sort fields are specified, the same random hash
|
|
+function is used for all fields. To use different random hash
|
|
+functions for different fields, you can invoke @command{sort} more
|
|
+than once.
|
|
+
|
|
+The choice of hash function is affected by the
|
|
+@option{--random-source} option.
|
|
+
|
|
+@end table
|
|
+
|
|
+Other options are:
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item --compress-program=@var{prog}
|
|
+Compress any temporary files with the program @var{prog}.
|
|
+
|
|
+With no arguments, @var{prog} must compress standard input to standard
|
|
+output, and when given the @option{-d} option it must decompress
|
|
+standard input to standard output.
|
|
+
|
|
+Terminate with an error if @var{prog} exits with nonzero status.
|
|
+
|
|
+White space and the backslash character should not appear in
|
|
+@var{prog}; they are reserved for future use.
|
|
+
|
|
+@filesZeroFromOption{sort,,sorted output}
|
|
+
|
|
+@item -k @var{pos1}[,@var{pos2}]
|
|
+@itemx --key=@var{pos1}[,@var{pos2}]
|
|
+@opindex -k
|
|
+@opindex --key
|
|
+@cindex sort field
|
|
+Specify a sort field that consists of the part of the line between
|
|
+@var{pos1} and @var{pos2} (or the end of the line, if @var{pos2} is
|
|
+omitted), @emph{inclusive}.
|
|
+
|
|
+Each @var{pos} has the form @samp{@var{f}[.@var{c}][@var{opts}]},
|
|
+where @var{f} is the number of the field to use, and @var{c} is the number
|
|
+of the first character from the beginning of the field. Fields and character
|
|
+positions are numbered starting with 1; a character position of zero in
|
|
+@var{pos2} indicates the field's last character. If @samp{.@var{c}} is
|
|
+omitted from @var{pos1}, it defaults to 1 (the beginning of the field);
|
|
+if omitted from @var{pos2}, it defaults to 0 (the end of the field).
|
|
+@var{opts} are ordering options, allowing individual keys to be sorted
|
|
+according to different rules; see below for details. Keys can span
|
|
+multiple fields.
|
|
+
|
|
+Example: To sort on the second field, use @option{--key=2,2}
|
|
+(@option{-k 2,2}). See below for more notes on keys and more examples.
|
|
+
|
|
+@item --batch-size=@var{nmerge}
|
|
+@opindex --batch-size
|
|
+@cindex number of inputs to merge, nmerge
|
|
+Merge at most @var{nmerge} inputs at once.
|
|
+
|
|
+When @command{sort} has to merge more than @var{nmerge} inputs,
|
|
+it merges them in groups of @var{nmerge}, saving the result in
|
|
+a temporary file, which is then used as an input in a subsequent merge.
|
|
+
|
|
+A large value of @var{nmerge} may improve merge performance and decrease
|
|
+temporary storage utilization at the expense of increased memory usage
|
|
+and I/0. Conversely a small value of @var{nmerge} may reduce memory
|
|
+requirements and I/0 at the expense of temporary storage consumption and
|
|
+merge performance.
|
|
+
|
|
+The value of @var{nmerge} must be at least 2. The default value is
|
|
+currently 16, but this is implementation-dependent and may change in
|
|
+the future.
|
|
+
|
|
+The value of @var{nmerge} may be bounded by a resource limit for open
|
|
+file descriptors. The commands @samp{ulimit -n} or @samp{getconf
|
|
+OPEN_MAX} may display limits for your systems; these limits may be
|
|
+modified further if your program already has some files open, or if
|
|
+the operating system has other limits on the number of open files. If
|
|
+the value of @var{nmerge} exceeds the resource limit, @command{sort}
|
|
+silently uses a smaller value.
|
|
+
|
|
+@item -o @var{output-file}
|
|
+@itemx --output=@var{output-file}
|
|
+@opindex -o
|
|
+@opindex --output
|
|
+@cindex overwriting of input, allowed
|
|
+Write output to @var{output-file} instead of standard output.
|
|
+Normally, @command{sort} reads all input before opening
|
|
+@var{output-file}, so you can safely sort a file in place by using
|
|
+commands like @code{sort -o F F} and @code{cat F | sort -o F}.
|
|
+However, @command{sort} with @option{--merge} (@option{-m}) can open
|
|
+the output file before reading all input, so a command like @code{cat
|
|
+F | sort -m -o F - G} is not safe as @command{sort} might start
|
|
+writing @file{F} before @command{cat} is done reading it.
|
|
+
|
|
+@vindex POSIXLY_CORRECT
|
|
+On newer systems, @option{-o} cannot appear after an input file if
|
|
+@env{POSIXLY_CORRECT} is set, e.g., @samp{sort F -o F}. Portable
|
|
+scripts should specify @option{-o @var{output-file}} before any input
|
|
+files.
|
|
+
|
|
+@item --random-source=@var{file}
|
|
+@opindex --random-source
|
|
+@cindex random source for sorting
|
|
+Use @var{file} as a source of random data used to determine which
|
|
+random hash function to use with the @option{-R} option. @xref{Random
|
|
+sources}.
|
|
+
|
|
+@item -s
|
|
+@itemx --stable
|
|
+@opindex -s
|
|
+@opindex --stable
|
|
+@cindex sort stability
|
|
+@cindex sort's last-resort comparison
|
|
+
|
|
+Make @command{sort} stable by disabling its last-resort comparison.
|
|
+This option has no effect if no fields or global ordering options
|
|
+other than @option{--reverse} (@option{-r}) are specified.
|
|
+
|
|
+@item -S @var{size}
|
|
+@itemx --buffer-size=@var{size}
|
|
+@opindex -S
|
|
+@opindex --buffer-size
|
|
+@cindex size for main memory sorting
|
|
+Use a main-memory sort buffer of the given @var{size}. By default,
|
|
+@var{size} is in units of 1024 bytes. Appending @samp{%} causes
|
|
+@var{size} to be interpreted as a percentage of physical memory.
|
|
+Appending @samp{K} multiplies @var{size} by 1024 (the default),
|
|
+@samp{M} by 1,048,576, @samp{G} by 1,073,741,824, and so on for
|
|
+@samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}. Appending
|
|
+@samp{b} causes @var{size} to be interpreted as a byte count, with no
|
|
+multiplication.
|
|
+
|
|
+This option can improve the performance of @command{sort} by causing it
|
|
+to start with a larger or smaller sort buffer than the default.
|
|
+However, this option affects only the initial buffer size. The buffer
|
|
+grows beyond @var{size} if @command{sort} encounters input lines larger
|
|
+than @var{size}.
|
|
+
|
|
+@item -t @var{separator}
|
|
+@itemx --field-separator=@var{separator}
|
|
+@opindex -t
|
|
+@opindex --field-separator
|
|
+@cindex field separator character
|
|
+Use character @var{separator} as the field separator when finding the
|
|
+sort keys in each line. By default, fields are separated by the empty
|
|
+string between a non-blank character and a blank character.
|
|
+By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
|
|
+can change this.
|
|
+
|
|
+That is, given the input line @w{@samp{ foo bar}}, @command{sort} breaks it
|
|
+into fields @w{@samp{ foo}} and @w{@samp{ bar}}. The field separator is
|
|
+not considered to be part of either the field preceding or the field
|
|
+following, so with @samp{sort @w{-t " "}} the same input line has
|
|
+three fields: an empty field, @samp{foo}, and @samp{bar}.
|
|
+However, fields that extend to the end of the line,
|
|
+as @option{-k 2}, or fields consisting of a range, as @option{-k 2,3},
|
|
+retain the field separators present between the endpoints of the range.
|
|
+
|
|
+To specify @acronym{ASCII} @sc{nul} as the field separator,
|
|
+use the two-character string @samp{\0}, e.g., @samp{sort -t '\0'}.
|
|
+
|
|
+@item -T @var{tempdir}
|
|
+@itemx --temporary-directory=@var{tempdir}
|
|
+@opindex -T
|
|
+@opindex --temporary-directory
|
|
+@cindex temporary directory
|
|
+@vindex TMPDIR
|
|
+Use directory @var{tempdir} to store temporary files, overriding the
|
|
+@env{TMPDIR} environment variable. If this option is given more than
|
|
+once, temporary files are stored in all the directories given. If you
|
|
+have a large sort or merge that is I/O-bound, you can often improve
|
|
+performance by using this option to specify directories on different
|
|
+disks and controllers.
|
|
+
|
|
+@item -u
|
|
+@itemx --unique
|
|
+@opindex -u
|
|
+@opindex --unique
|
|
+@cindex uniquifying output
|
|
+
|
|
+Normally, output only the first of a sequence of lines that compare
|
|
+equal. For the @option{--check} (@option{-c} or @option{-C}) option,
|
|
+check that no pair of consecutive lines compares equal.
|
|
+
|
|
+This option also disables the default last-resort comparison.
|
|
+
|
|
+The commands @code{sort -u} and @code{sort | uniq} are equivalent, but
|
|
+this equivalence does not extend to arbitrary @command{sort} options.
|
|
+For example, @code{sort -n -u} inspects only the value of the initial
|
|
+numeric string when checking for uniqueness, whereas @code{sort -n |
|
|
+uniq} inspects the entire line. @xref{uniq invocation}.
|
|
+
|
|
+@macro zeroTerminatedOption
|
|
+@item -z
|
|
+@itemx --zero-terminated
|
|
+@opindex -z
|
|
+@opindex --zero-terminated
|
|
+@cindex process zero-terminated items
|
|
+Delimit items with a zero byte rather than a newline (@acronym{ASCII} @sc{lf}).
|
|
+I.E. treat input as items separated by @acronym{ASCII} @sc{nul}
|
|
+and terminate output items with @acronym{ASCII} @sc{nul}.
|
|
+This option can be useful in conjunction with @samp{perl -0} or
|
|
+@samp{find -print0} and @samp{xargs -0} which do the same in order to
|
|
+reliably handle arbitrary file names (even those containing blanks
|
|
+or other special characters).
|
|
+@end macro
|
|
+@zeroTerminatedOption
|
|
+
|
|
+@end table
|
|
+
|
|
+Historical (BSD and System V) implementations of @command{sort} have
|
|
+differed in their interpretation of some options, particularly
|
|
+@option{-b}, @option{-f}, and @option{-n}. @sc{gnu} sort follows the @acronym{POSIX}
|
|
+behavior, which is usually (but not always!) like the System V behavior.
|
|
+According to @acronym{POSIX}, @option{-n} no longer implies @option{-b}. For
|
|
+consistency, @option{-M} has been changed in the same way. This may
|
|
+affect the meaning of character positions in field specifications in
|
|
+obscure cases. The only fix is to add an explicit @option{-b}.
|
|
+
|
|
+A position in a sort field specified with @option{-k} may have any
|
|
+of the option letters @samp{MbdfghinRrV} appended to it, in which case no
|
|
+global ordering options are inherited by that particular field. The
|
|
+@option{-b} option may be independently attached to either or both of
|
|
+the start and end positions of a field specification, and if it is
|
|
+inherited from the global options it will be attached to both.
|
|
+If input lines can contain leading or adjacent blanks and @option{-t}
|
|
+is not used, then @option{-k} is typically combined with @option{-b} or
|
|
+an option that implicitly ignores leading blanks (@samp{MghnV}) as otherwise
|
|
+the varying numbers of leading blanks in fields can cause confusing results.
|
|
+
|
|
+If the start position in a sort field specifier falls after the end of
|
|
+the line or after the end field, the field is empty. If the @option{-b}
|
|
+option was specified, the @samp{.@var{c}} part of a field specification
|
|
+is counted from the first nonblank character of the field.
|
|
+
|
|
+@vindex _POSIX2_VERSION
|
|
+@vindex POSIXLY_CORRECT
|
|
+On older systems, @command{sort} supports an obsolete origin-zero
|
|
+syntax @samp{+@var{pos1} [-@var{pos2}]} for specifying sort keys.
|
|
+This obsolete behavior can be enabled or disabled with the
|
|
+@env{_POSIX2_VERSION} environment variable (@pxref{Standards
|
|
+conformance}); it can also be enabled when @env{POSIXLY_CORRECT} is
|
|
+not set by using the obsolete syntax with @samp{-@var{pos2}} present.
|
|
+
|
|
+Scripts intended for use on standard hosts should avoid obsolete
|
|
+syntax and should use @option{-k} instead. For example, avoid
|
|
+@samp{sort +2}, since it might be interpreted as either @samp{sort
|
|
+./+2} or @samp{sort -k 3}. If your script must also run on hosts that
|
|
+support only the obsolete syntax, it can use a test like @samp{if sort
|
|
+-k 1 </dev/null >/dev/null 2>&1; then @dots{}} to decide which syntax
|
|
+to use.
|
|
+
|
|
+Here are some examples to illustrate various combinations of options.
|
|
+
|
|
+@itemize @bullet
|
|
+
|
|
+@item
|
|
+Sort in descending (reverse) numeric order.
|
|
+
|
|
+@example
|
|
+sort -n -r
|
|
+@end example
|
|
+
|
|
+@item
|
|
+Sort alphabetically, omitting the first and second fields
|
|
+and the blanks at the start of the third field.
|
|
+This uses a single key composed of the characters beginning
|
|
+at the start of the first nonblank character in field three
|
|
+and extending to the end of each line.
|
|
+
|
|
+@example
|
|
+sort -k 3b
|
|
+@end example
|
|
+
|
|
+@item
|
|
+Sort numerically on the second field and resolve ties by sorting
|
|
+alphabetically on the third and fourth characters of field five.
|
|
+Use @samp{:} as the field delimiter.
|
|
+
|
|
+@example
|
|
+sort -t : -k 2,2n -k 5.3,5.4
|
|
+@end example
|
|
+
|
|
+Note that if you had written @option{-k 2n} instead of @option{-k 2,2n}
|
|
+@command{sort} would have used all characters beginning in the second field
|
|
+and extending to the end of the line as the primary @emph{numeric}
|
|
+key. For the large majority of applications, treating keys spanning
|
|
+more than one field as numeric will not do what you expect.
|
|
+
|
|
+Also note that the @samp{n} modifier was applied to the field-end
|
|
+specifier for the first key. It would have been equivalent to
|
|
+specify @option{-k 2n,2} or @option{-k 2n,2n}. All modifiers except
|
|
+@samp{b} apply to the associated @emph{field}, regardless of whether
|
|
+the modifier character is attached to the field-start and/or the
|
|
+field-end part of the key specifier.
|
|
+
|
|
+@item
|
|
+Sort the password file on the fifth field and ignore any
|
|
+leading blanks. Sort lines with equal values in field five
|
|
+on the numeric user ID in field three. Fields are separated
|
|
+by @samp{:}.
|
|
+
|
|
+@example
|
|
+sort -t : -k 5b,5 -k 3,3n /etc/passwd
|
|
+sort -t : -n -k 5b,5 -k 3,3 /etc/passwd
|
|
+sort -t : -b -k 5,5 -k 3,3n /etc/passwd
|
|
+@end example
|
|
+
|
|
+These three commands have equivalent effect. The first specifies that
|
|
+the first key's start position ignores leading blanks and the second
|
|
+key is sorted numerically. The other two commands rely on global
|
|
+options being inherited by sort keys that lack modifiers. The inheritance
|
|
+works in this case because @option{-k 5b,5b} and @option{-k 5b,5} are
|
|
+equivalent, as the location of a field-end lacking a @samp{.@var{c}}
|
|
+character position is not affected by whether initial blanks are
|
|
+skipped.
|
|
+
|
|
+@item
|
|
+Sort a set of log files, primarily by IPv4 address and secondarily by
|
|
+time stamp. If two lines' primary and secondary keys are identical,
|
|
+output the lines in the same order that they were input. The log
|
|
+files contain lines that look like this:
|
|
+
|
|
+@example
|
|
+4.150.156.3 - - [01/Apr/2004:06:31:51 +0000] message 1
|
|
+211.24.3.231 - - [24/Apr/2004:20:17:39 +0000] message 2
|
|
+@end example
|
|
+
|
|
+Fields are separated by exactly one space. Sort IPv4 addresses
|
|
+lexicographically, e.g., 212.61.52.2 sorts before 212.129.233.201
|
|
+because 61 is less than 129.
|
|
+
|
|
+@example
|
|
+sort -s -t ' ' -k 4.9n -k 4.5M -k 4.2n -k 4.14,4.21 file*.log |
|
|
+sort -s -t '.' -k 1,1n -k 2,2n -k 3,3n -k 4,4n
|
|
+@end example
|
|
+
|
|
+This example cannot be done with a single @command{sort} invocation,
|
|
+since IPv4 address components are separated by @samp{.} while dates
|
|
+come just after a space. So it is broken down into two invocations of
|
|
+@command{sort}: the first sorts by time stamp and the second by IPv4
|
|
+address. The time stamp is sorted by year, then month, then day, and
|
|
+finally by hour-minute-second field, using @option{-k} to isolate each
|
|
+field. Except for hour-minute-second there's no need to specify the
|
|
+end of each key field, since the @samp{n} and @samp{M} modifiers sort
|
|
+based on leading prefixes that cannot cross field boundaries. The
|
|
+IPv4 addresses are sorted lexicographically. The second sort uses
|
|
+@samp{-s} so that ties in the primary key are broken by the secondary
|
|
+key; the first sort uses @samp{-s} so that the combination of the two
|
|
+sorts is stable.
|
|
+
|
|
+@item
|
|
+Generate a tags file in case-insensitive sorted order.
|
|
+
|
|
+@smallexample
|
|
+find src -type f -print0 | sort -z -f | xargs -0 etags --append
|
|
+@end smallexample
|
|
+
|
|
+The use of @option{-print0}, @option{-z}, and @option{-0} in this case means
|
|
+that file names that contain blanks or other special characters are
|
|
+not broken up
|
|
+by the sort operation.
|
|
+
|
|
+@c This example is a bit contrived and needs more explanation.
|
|
+@c @item
|
|
+@c Sort records separated by an arbitrary string by using a pipe to convert
|
|
+@c each record delimiter string to @samp{\0}, then using sort's -z option,
|
|
+@c and converting each @samp{\0} back to the original record delimiter.
|
|
+@c
|
|
+@c @example
|
|
+@c printf 'c\n\nb\n\na\n'|perl -0pe 's/\n\n/\n\0/g'|sort -z|perl -0pe 's/\0/\n/g'
|
|
+@c @end example
|
|
+
|
|
+@item
|
|
+Use the common @acronym{DSU, Decorate Sort Undecorate} idiom to
|
|
+sort lines according to their length.
|
|
+
|
|
+@example
|
|
+awk '@{print length, $0@}' /etc/passwd | sort -n | cut -f2- -d' '
|
|
+@end example
|
|
+
|
|
+In general this technique can be used to sort data that the @command{sort}
|
|
+command does not support, or is inefficient at, sorting directly.
|
|
+
|
|
+@item
|
|
+Shuffle a list of directories, but preserve the order of files within
|
|
+each directory. For instance, one could use this to generate a music
|
|
+playlist in which albums are shuffled but the songs of each album are
|
|
+played in order.
|
|
+
|
|
+@example
|
|
+ls */* | sort -t / -k 1,1R -k 2,2
|
|
+@end example
|
|
+
|
|
+@end itemize
|
|
+
|
|
+
|
|
+@node shuf invocation
|
|
+@section @command{shuf}: Shuffling text
|
|
+
|
|
+@pindex shuf
|
|
+@cindex shuffling files
|
|
+
|
|
+@command{shuf} shuffles its input by outputting a random permutation
|
|
+of its input lines. Each output permutation is equally likely.
|
|
+Synopses:
|
|
+
|
|
+@example
|
|
+shuf [@var{option}]@dots{} [@var{file}]
|
|
+shuf -e [@var{option}]@dots{} [@var{arg}]@dots{}
|
|
+shuf -i @var{lo}-@var{hi} [@var{option}]@dots{}
|
|
+@end example
|
|
+
|
|
+@command{shuf} has three modes of operation that affect where it
|
|
+obtains its input lines. By default, it reads lines from standard
|
|
+input. The following options change the operation mode:
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -e
|
|
+@itemx --echo
|
|
+@opindex -c
|
|
+@opindex --echo
|
|
+@cindex command-line operands to shuffle
|
|
+Treat each command-line operand as an input line.
|
|
+
|
|
+@item -i @var{lo}-@var{hi}
|
|
+@itemx --input-range=@var{lo}-@var{hi}
|
|
+@opindex -i
|
|
+@opindex --input-range
|
|
+@cindex input range to shuffle
|
|
+Act as if input came from a file containing the range of unsigned
|
|
+decimal integers @var{lo}@dots{}@var{hi}, one per line.
|
|
+
|
|
+@end table
|
|
+
|
|
+@command{shuf}'s other options can affect its behavior in all
|
|
+operation modes:
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -n @var{lines}
|
|
+@itemx --head-count=@var{count}
|
|
+@opindex -n
|
|
+@opindex --head-count
|
|
+@cindex head of output
|
|
+Output at most @var{count} lines. By default, all input lines are
|
|
+output.
|
|
+
|
|
+@item -o @var{output-file}
|
|
+@itemx --output=@var{output-file}
|
|
+@opindex -o
|
|
+@opindex --output
|
|
+@cindex overwriting of input, allowed
|
|
+Write output to @var{output-file} instead of standard output.
|
|
+@command{shuf} reads all input before opening
|
|
+@var{output-file}, so you can safely shuffle a file in place by using
|
|
+commands like @code{shuf -o F <F} and @code{cat F | shuf -o F}.
|
|
+
|
|
+@item --random-source=@var{file}
|
|
+@opindex --random-source
|
|
+@cindex random source for shuffling
|
|
+Use @var{file} as a source of random data used to determine which
|
|
+permutation to generate. @xref{Random sources}.
|
|
+
|
|
+@zeroTerminatedOption
|
|
+
|
|
+@end table
|
|
+
|
|
+For example:
|
|
+
|
|
+@example
|
|
+shuf <<EOF
|
|
+A man,
|
|
+a plan,
|
|
+a canal:
|
|
+Panama!
|
|
+EOF
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+might produce the output
|
|
+
|
|
+@example
|
|
+Panama!
|
|
+A man,
|
|
+a canal:
|
|
+a plan,
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+Similarly, the command:
|
|
+
|
|
+@example
|
|
+shuf -e clubs hearts diamonds spades
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+might output:
|
|
+
|
|
+@example
|
|
+clubs
|
|
+diamonds
|
|
+spades
|
|
+hearts
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+and the command @samp{shuf -i 1-4} might output:
|
|
+
|
|
+@example
|
|
+4
|
|
+2
|
|
+1
|
|
+3
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+These examples all have four input lines, so @command{shuf} might
|
|
+produce any of the twenty-four possible permutations of the input. In
|
|
+general, if there are @var{n} input lines, there are @var{n}! (i.e.,
|
|
+@var{n} factorial, or @var{n} * (@var{n} - 1) * @dots{} * 1) possible
|
|
+output permutations.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node uniq invocation
|
|
+@section @command{uniq}: Uniquify files
|
|
+
|
|
+@pindex uniq
|
|
+@cindex uniquify files
|
|
+
|
|
+@command{uniq} writes the unique lines in the given @file{input}, or
|
|
+standard input if nothing is given or for an @var{input} name of
|
|
+@samp{-}. Synopsis:
|
|
+
|
|
+@example
|
|
+uniq [@var{option}]@dots{} [@var{input} [@var{output}]]
|
|
+@end example
|
|
+
|
|
+By default, @command{uniq} prints its input lines, except that
|
|
+it discards all but the first of adjacent repeated lines, so that
|
|
+no output lines are repeated. Optionally, it can instead discard
|
|
+lines that are not repeated, or all repeated lines.
|
|
+
|
|
+The input need not be sorted, but repeated input lines are detected
|
|
+only if they are adjacent. If you want to discard non-adjacent
|
|
+duplicate lines, perhaps you want to use @code{sort -u}.
|
|
+@xref{sort invocation}.
|
|
+
|
|
+@vindex LC_COLLATE
|
|
+Comparisons honor the rules specified by the @env{LC_COLLATE}
|
|
+locale category.
|
|
+
|
|
+If no @var{output} file is specified, @command{uniq} writes to standard
|
|
+output.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -f @var{n}
|
|
+@itemx --skip-fields=@var{n}
|
|
+@opindex -f
|
|
+@opindex --skip-fields
|
|
+Skip @var{n} fields on each line before checking for uniqueness. Use
|
|
+a null string for comparison if a line has fewer than @var{n} fields. Fields
|
|
+are sequences of non-space non-tab characters that are separated from
|
|
+each other by at least one space or tab.
|
|
+
|
|
+For compatibility @command{uniq} supports an obsolete option syntax
|
|
+@option{-@var{n}}. New scripts should use @option{-f @var{n}} instead.
|
|
+
|
|
+@item -s @var{n}
|
|
+@itemx --skip-chars=@var{n}
|
|
+@opindex -s
|
|
+@opindex --skip-chars
|
|
+Skip @var{n} characters before checking for uniqueness. Use a null string
|
|
+for comparison if a line has fewer than @var{n} characters. If you use both
|
|
+the field and character skipping options, fields are skipped over first.
|
|
+
|
|
+@vindex _POSIX2_VERSION
|
|
+On older systems, @command{uniq} supports an obsolete option syntax
|
|
+@option{+@var{n}}.
|
|
+This obsolete behavior can be enabled or disabled with the
|
|
+@env{_POSIX2_VERSION} environment variable (@pxref{Standards
|
|
+conformance}), but portable scripts should avoid commands whose
|
|
+behavior depends on this variable.
|
|
+For example, use @samp{uniq ./+10} or @samp{uniq -s 10} rather than
|
|
+the ambiguous @samp{uniq +10}.
|
|
+
|
|
+@item -c
|
|
+@itemx --count
|
|
+@opindex -c
|
|
+@opindex --count
|
|
+Print the number of times each line occurred along with the line.
|
|
+
|
|
+@item -i
|
|
+@itemx --ignore-case
|
|
+@opindex -i
|
|
+@opindex --ignore-case
|
|
+Ignore differences in case when comparing lines.
|
|
+
|
|
+@item -d
|
|
+@itemx --repeated
|
|
+@opindex -d
|
|
+@opindex --repeated
|
|
+@cindex repeated lines, outputting
|
|
+Discard lines that are not repeated. When used by itself, this option
|
|
+causes @command{uniq} to print the first copy of each repeated line,
|
|
+and nothing else.
|
|
+
|
|
+@item -D
|
|
+@itemx --all-repeated[=@var{delimit-method}]
|
|
+@opindex -D
|
|
+@opindex --all-repeated
|
|
+@cindex all repeated lines, outputting
|
|
+Do not discard the second and subsequent repeated input lines,
|
|
+but discard lines that are not repeated.
|
|
+This option is useful mainly in conjunction with other options e.g.,
|
|
+to ignore case or to compare only selected fields.
|
|
+The optional @var{delimit-method} tells how to delimit
|
|
+groups of repeated lines, and must be one of the following:
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item none
|
|
+Do not delimit groups of repeated lines.
|
|
+This is equivalent to @option{--all-repeated} (@option{-D}).
|
|
+
|
|
+@item prepend
|
|
+Output a newline before each group of repeated lines.
|
|
+With @option{--zero-terminated} (@option{-z}), use a zero
|
|
+byte (@acronym{ASCII} @sc{nul}) instead of a newline.
|
|
+
|
|
+@item separate
|
|
+Separate groups of repeated lines with a single newline.
|
|
+With @option{--zero-terminated} (@option{-z}), use a zero
|
|
+byte (@acronym{ASCII} @sc{nul}) instead of a newline.
|
|
+This is the same as using @samp{prepend}, except that
|
|
+no delimiter is inserted before the first group, and hence
|
|
+may be better suited for output direct to users.
|
|
+@end table
|
|
+
|
|
+Note that when groups are delimited and the input stream contains
|
|
+two or more consecutive blank lines, then the output is ambiguous.
|
|
+To avoid that, filter the input through @samp{tr -s '\n'} to replace
|
|
+each sequence of consecutive newlines with a single newline.
|
|
+
|
|
+This is a @sc{gnu} extension.
|
|
+@c FIXME: give an example showing *how* it's useful
|
|
+
|
|
+@item -u
|
|
+@itemx --unique
|
|
+@opindex -u
|
|
+@opindex --unique
|
|
+@cindex unique lines, outputting
|
|
+Discard the first repeated line. When used by itself, this option
|
|
+causes @command{uniq} to print unique lines, and nothing else.
|
|
+
|
|
+@item -w @var{n}
|
|
+@itemx --check-chars=@var{n}
|
|
+@opindex -w
|
|
+@opindex --check-chars
|
|
+Compare at most @var{n} characters on each line (after skipping any specified
|
|
+fields and characters). By default the entire rest of the lines are
|
|
+compared.
|
|
+
|
|
+@zeroTerminatedOption
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node comm invocation
|
|
+@section @command{comm}: Compare two sorted files line by line
|
|
+
|
|
+@pindex comm
|
|
+@cindex line-by-line comparison
|
|
+@cindex comparing sorted files
|
|
+
|
|
+@command{comm} writes to standard output lines that are common, and lines
|
|
+that are unique, to two input files; a file name of @samp{-} means
|
|
+standard input. Synopsis:
|
|
+
|
|
+@example
|
|
+comm [@var{option}]@dots{} @var{file1} @var{file2}
|
|
+@end example
|
|
+
|
|
+@vindex LC_COLLATE
|
|
+Before @command{comm} can be used, the input files must be sorted using the
|
|
+collating sequence specified by the @env{LC_COLLATE} locale.
|
|
+If an input file ends in a non-newline
|
|
+character, a newline is silently appended. The @command{sort} command with
|
|
+no options always outputs a file that is suitable input to @command{comm}.
|
|
+
|
|
+@cindex differing lines
|
|
+@cindex common lines
|
|
+With no options, @command{comm} produces three-column output. Column one
|
|
+contains lines unique to @var{file1}, column two contains lines unique
|
|
+to @var{file2}, and column three contains lines common to both files.
|
|
+Columns are separated by a single TAB character.
|
|
+@c FIXME: when there's an option to supply an alternative separator
|
|
+@c string, append `by default' to the above sentence.
|
|
+
|
|
+@opindex -1
|
|
+@opindex -2
|
|
+@opindex -3
|
|
+The options @option{-1}, @option{-2}, and @option{-3} suppress printing of
|
|
+the corresponding columns (and separators). Also see @ref{Common options}.
|
|
+
|
|
+Unlike some other comparison utilities, @command{comm} has an exit
|
|
+status that does not depend on the result of the comparison.
|
|
+Upon normal completion @command{comm} produces an exit code of zero.
|
|
+If there is an error it exits with nonzero status.
|
|
+
|
|
+@macro checkOrderOption{cmd}
|
|
+If the @option{--check-order} option is given, unsorted inputs will
|
|
+cause a fatal error message. If the option @option{--nocheck-order}
|
|
+is given, unsorted inputs will never cause an error message. If
|
|
+neither of these options is given, wrongly sorted inputs are diagnosed
|
|
+only if an input file is found to contain unpairable lines. If an
|
|
+input file is diagnosed as being unsorted, the @command{\cmd\} command
|
|
+will exit with a nonzero status (and the output should not be used).
|
|
+
|
|
+Forcing @command{\cmd\} to process wrongly sorted input files
|
|
+containing unpairable lines by specifying @option{--nocheck-order} is
|
|
+not guaranteed to produce any particular output. The output will
|
|
+probably not correspond with whatever you hoped it would be.
|
|
+@end macro
|
|
+@checkOrderOption{comm}
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item --check-order
|
|
+Fail with an error message if either input file is wrongly ordered.
|
|
+
|
|
+@item --nocheck-order
|
|
+Do not check that both input files are in sorted order.
|
|
+
|
|
+Other options are:
|
|
+
|
|
+@item --output-delimiter=@var{str}
|
|
+Print @var{str} between adjacent output columns,
|
|
+rather than the default of a single TAB character.
|
|
+
|
|
+The delimiter @var{str} may not be empty.
|
|
+
|
|
+@end table
|
|
+
|
|
+@node ptx invocation
|
|
+@section @command{ptx}: Produce permuted indexes
|
|
+
|
|
+@pindex ptx
|
|
+
|
|
+@command{ptx} reads a text file and essentially produces a permuted index, with
|
|
+each keyword in its context. The calling sketch is either one of:
|
|
+
|
|
+@example
|
|
+ptx [@var{option} @dots{}] [@var{file} @dots{}]
|
|
+ptx -G [@var{option} @dots{}] [@var{input} [@var{output}]]
|
|
+@end example
|
|
+
|
|
+The @option{-G} (or its equivalent: @option{--traditional}) option disables
|
|
+all @sc{gnu} extensions and reverts to traditional mode, thus introducing some
|
|
+limitations and changing several of the program's default option values.
|
|
+When @option{-G} is not specified, @sc{gnu} extensions are always enabled.
|
|
+@sc{gnu} extensions to @command{ptx} are documented wherever appropriate in this
|
|
+document. For the full list, see @xref{Compatibility in ptx}.
|
|
+
|
|
+Individual options are explained in the following sections.
|
|
+
|
|
+When @sc{gnu} extensions are enabled, there may be zero, one or several
|
|
+@var{file}s after the options. If there is no @var{file}, the program
|
|
+reads the standard input. If there is one or several @var{file}s, they
|
|
+give the name of input files which are all read in turn, as if all the
|
|
+input files were concatenated. However, there is a full contextual
|
|
+break between each file and, when automatic referencing is requested,
|
|
+file names and line numbers refer to individual text input files. In
|
|
+all cases, the program outputs the permuted index to the standard
|
|
+output.
|
|
+
|
|
+When @sc{gnu} extensions are @emph{not} enabled, that is, when the program
|
|
+operates in traditional mode, there may be zero, one or two parameters
|
|
+besides the options. If there are no parameters, the program reads the
|
|
+standard input and outputs the permuted index to the standard output.
|
|
+If there is only one parameter, it names the text @var{input} to be read
|
|
+instead of the standard input. If two parameters are given, they give
|
|
+respectively the name of the @var{input} file to read and the name of
|
|
+the @var{output} file to produce. @emph{Be very careful} to note that,
|
|
+in this case, the contents of file given by the second parameter is
|
|
+destroyed. This behavior is dictated by System V @command{ptx}
|
|
+compatibility; @sc{gnu} Standards normally discourage output parameters not
|
|
+introduced by an option.
|
|
+
|
|
+Note that for @emph{any} file named as the value of an option or as an
|
|
+input text file, a single dash @kbd{-} may be used, in which case
|
|
+standard input is assumed. However, it would not make sense to use this
|
|
+convention more than once per program invocation.
|
|
+
|
|
+@menu
|
|
+* 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::
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node General options in ptx
|
|
+@subsection General options
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -G
|
|
+@itemx --traditional
|
|
+As already explained, this option disables all @sc{gnu} extensions to
|
|
+@command{ptx} and switches to traditional mode.
|
|
+
|
|
+@item --help
|
|
+Print a short help on standard output, then exit without further
|
|
+processing.
|
|
+
|
|
+@item --version
|
|
+Print the program version on standard output, then exit without further
|
|
+processing.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node Charset selection in ptx
|
|
+@subsection Charset selection
|
|
+
|
|
+@c FIXME: People don't necessarily know what an IBM-PC was these days.
|
|
+As it is set up now, the program assumes that the input file is coded
|
|
+using 8-bit @acronym{ISO} 8859-1 code, also known as Latin-1 character set,
|
|
+@emph{unless} it is compiled for MS-DOS, in which case it uses the
|
|
+character set of the IBM-PC@. (@sc{gnu} @command{ptx} is not known to work on
|
|
+smaller MS-DOS machines anymore.) Compared to 7-bit @acronym{ASCII}, the set
|
|
+of characters which are letters is different; this alters the behavior
|
|
+of regular expression matching. Thus, the default regular expression
|
|
+for a keyword allows foreign or diacriticized letters. Keyword sorting,
|
|
+however, is still crude; it obeys the underlying character set ordering
|
|
+quite blindly.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -f
|
|
+@itemx --ignore-case
|
|
+Fold lower case letters to upper case for sorting.
|
|
+
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Input processing in ptx
|
|
+@subsection Word selection and input processing
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -b @var{file}
|
|
+@itemx --break-file=@var{file}
|
|
+
|
|
+This option provides an alternative (to @option{-W}) method of describing
|
|
+which characters make up words. It introduces the name of a
|
|
+file which contains a list of characters which can@emph{not} be part of
|
|
+one word; this file is called the @dfn{Break file}. Any character which
|
|
+is not part of the Break file is a word constituent. If both options
|
|
+@option{-b} and @option{-W} are specified, then @option{-W} has precedence and
|
|
+@option{-b} is ignored.
|
|
+
|
|
+When @sc{gnu} extensions are enabled, the only way to avoid newline as a
|
|
+break character is to write all the break characters in the file with no
|
|
+newline at all, not even at the end of the file. When @sc{gnu} extensions
|
|
+are disabled, spaces, tabs and newlines are always considered as break
|
|
+characters even if not included in the Break file.
|
|
+
|
|
+@item -i @var{file}
|
|
+@itemx --ignore-file=@var{file}
|
|
+
|
|
+The file associated with this option contains a list of words which will
|
|
+never be taken as keywords in concordance output. It is called the
|
|
+@dfn{Ignore file}. The file contains exactly one word in each line; the
|
|
+end of line separation of words is not subject to the value of the
|
|
+@option{-S} option.
|
|
+
|
|
+@item -o @var{file}
|
|
+@itemx --only-file=@var{file}
|
|
+
|
|
+The file associated with this option contains a list of words which will
|
|
+be retained in concordance output; any word not mentioned in this file
|
|
+is ignored. The file is called the @dfn{Only file}. The file contains
|
|
+exactly one word in each line; the end of line separation of words is
|
|
+not subject to the value of the @option{-S} option.
|
|
+
|
|
+There is no default for the Only file. When both an Only file and an
|
|
+Ignore file are specified, a word is considered a keyword only
|
|
+if it is listed in the Only file and not in the Ignore file.
|
|
+
|
|
+@item -r
|
|
+@itemx --references
|
|
+
|
|
+On each input line, the leading sequence of non-white space characters will be
|
|
+taken to be a reference that has the purpose of identifying this input
|
|
+line in the resulting permuted index. For more information about reference
|
|
+production, see @xref{Output formatting in ptx}.
|
|
+Using this option changes the default value for option @option{-S}.
|
|
+
|
|
+Using this option, the program does not try very hard to remove
|
|
+references from contexts in output, but it succeeds in doing so
|
|
+@emph{when} the context ends exactly at the newline. If option
|
|
+@option{-r} is used with @option{-S} default value, or when @sc{gnu} extensions
|
|
+are disabled, this condition is always met and references are completely
|
|
+excluded from the output contexts.
|
|
+
|
|
+@item -S @var{regexp}
|
|
+@itemx --sentence-regexp=@var{regexp}
|
|
+
|
|
+This option selects which regular expression will describe the end of a
|
|
+line or the end of a sentence. In fact, this regular expression is not
|
|
+the only distinction between end of lines or end of sentences, and input
|
|
+line boundaries have no special significance outside this option. By
|
|
+default, when @sc{gnu} extensions are enabled and if @option{-r} option is not
|
|
+used, end of sentences are used. In this case, this @var{regex} is
|
|
+imported from @sc{gnu} Emacs:
|
|
+
|
|
+@example
|
|
+[.?!][]\"')@}]*\\($\\|\t\\| \\)[ \t\n]*
|
|
+@end example
|
|
+
|
|
+Whenever @sc{gnu} extensions are disabled or if @option{-r} option is used, end
|
|
+of lines are used; in this case, the default @var{regexp} is just:
|
|
+
|
|
+@example
|
|
+\n
|
|
+@end example
|
|
+
|
|
+Using an empty @var{regexp} is equivalent to completely disabling end of
|
|
+line or end of sentence recognition. In this case, the whole file is
|
|
+considered to be a single big line or sentence. The user might want to
|
|
+disallow all truncation flag generation as well, through option @option{-F
|
|
+""}. @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
|
|
+Manual}.
|
|
+
|
|
+When the keywords happen to be near the beginning of the input line or
|
|
+sentence, this often creates an unused area at the beginning of the
|
|
+output context line; when the keywords happen to be near the end of the
|
|
+input line or sentence, this often creates an unused area at the end of
|
|
+the output context line. The program tries to fill those unused areas
|
|
+by wrapping around context in them; the tail of the input line or
|
|
+sentence is used to fill the unused area on the left of the output line;
|
|
+the head of the input line or sentence is used to fill the unused area
|
|
+on the right of the output line.
|
|
+
|
|
+As a matter of convenience to the user, many usual backslashed escape
|
|
+sequences from the C language are recognized and converted to the
|
|
+corresponding characters by @command{ptx} itself.
|
|
+
|
|
+@item -W @var{regexp}
|
|
+@itemx --word-regexp=@var{regexp}
|
|
+
|
|
+This option selects which regular expression will describe each keyword.
|
|
+By default, if @sc{gnu} extensions are enabled, a word is a sequence of
|
|
+letters; the @var{regexp} used is @samp{\w+}. When @sc{gnu} extensions are
|
|
+disabled, a word is by default anything which ends with a space, a tab
|
|
+or a newline; the @var{regexp} used is @samp{[^ \t\n]+}.
|
|
+
|
|
+An empty @var{regexp} is equivalent to not using this option.
|
|
+@xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
|
|
+Manual}.
|
|
+
|
|
+As a matter of convenience to the user, many usual backslashed escape
|
|
+sequences, as found in the C language, are recognized and converted to
|
|
+the corresponding characters by @command{ptx} itself.
|
|
+
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Output formatting in ptx
|
|
+@subsection Output formatting
|
|
+
|
|
+Output format is mainly controlled by the @option{-O} and @option{-T} options
|
|
+described in the table below. When neither @option{-O} nor @option{-T} are
|
|
+selected, and if @sc{gnu} extensions are enabled, the program chooses an
|
|
+output format suitable for a dumb terminal. Each keyword occurrence is
|
|
+output to the center of one line, surrounded by its left and right
|
|
+contexts. Each field is properly justified, so the concordance output
|
|
+can be readily observed. As a special feature, if automatic
|
|
+references are selected by option @option{-A} and are output before the
|
|
+left context, that is, if option @option{-R} is @emph{not} selected, then
|
|
+a colon is added after the reference; this nicely interfaces with @sc{gnu}
|
|
+Emacs @code{next-error} processing. In this default output format, each
|
|
+white space character, like newline and tab, is merely changed to
|
|
+exactly one space, with no special attempt to compress consecutive
|
|
+spaces. This might change in the future. Except for those white space
|
|
+characters, every other character of the underlying set of 256
|
|
+characters is transmitted verbatim.
|
|
+
|
|
+Output format is further controlled by the following options.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -g @var{number}
|
|
+@itemx --gap-size=@var{number}
|
|
+
|
|
+Select the size of the minimum white space gap between the fields on the
|
|
+output line.
|
|
+
|
|
+@item -w @var{number}
|
|
+@itemx --width=@var{number}
|
|
+
|
|
+Select the maximum output width of each final line. If references are
|
|
+used, they are included or excluded from the maximum output width
|
|
+depending on the value of option @option{-R}. If this option is not
|
|
+selected, that is, when references are output before the left context,
|
|
+the maximum output width takes into account the maximum length of all
|
|
+references. If this option is selected, that is, when references are
|
|
+output after the right context, the maximum output width does not take
|
|
+into account the space taken by references, nor the gap that precedes
|
|
+them.
|
|
+
|
|
+@item -A
|
|
+@itemx --auto-reference
|
|
+
|
|
+Select automatic references. Each input line will have an automatic
|
|
+reference made up of the file name and the line ordinal, with a single
|
|
+colon between them. However, the file name will be empty when standard
|
|
+input is being read. If both @option{-A} and @option{-r} are selected, then
|
|
+the input reference is still read and skipped, but the automatic
|
|
+reference is used at output time, overriding the input reference.
|
|
+
|
|
+@item -R
|
|
+@itemx --right-side-refs
|
|
+
|
|
+In the default output format, when option @option{-R} is not used, any
|
|
+references produced by the effect of options @option{-r} or @option{-A} are
|
|
+placed to the far right of output lines, after the right context. With
|
|
+default output format, when the @option{-R} option is specified, references
|
|
+are rather placed at the beginning of each output line, before the left
|
|
+context. For any other output format, option @option{-R} is
|
|
+ignored, with one exception: with @option{-R} the width of references
|
|
+is @emph{not} taken into account in total output width given by @option{-w}.
|
|
+
|
|
+This option is automatically selected whenever @sc{gnu} extensions are
|
|
+disabled.
|
|
+
|
|
+@item -F @var{string}
|
|
+@itemx --flac-truncation=@var{string}
|
|
+
|
|
+This option will request that any truncation in the output be reported
|
|
+using the string @var{string}. Most output fields theoretically extend
|
|
+towards the beginning or the end of the current line, or current
|
|
+sentence, as selected with option @option{-S}. But there is a maximum
|
|
+allowed output line width, changeable through option @option{-w}, which is
|
|
+further divided into space for various output fields. When a field has
|
|
+to be truncated because it cannot extend beyond the beginning or the end of
|
|
+the current line to fit in, then a truncation occurs. By default,
|
|
+the string used is a single slash, as in @option{-F /}.
|
|
+
|
|
+@var{string} may have more than one character, as in @option{-F ...}.
|
|
+Also, in the particular case when @var{string} is empty (@option{-F ""}),
|
|
+truncation flagging is disabled, and no truncation marks are appended in
|
|
+this case.
|
|
+
|
|
+As a matter of convenience to the user, many usual backslashed escape
|
|
+sequences, as found in the C language, are recognized and converted to
|
|
+the corresponding characters by @command{ptx} itself.
|
|
+
|
|
+@item -M @var{string}
|
|
+@itemx --macro-name=@var{string}
|
|
+
|
|
+Select another @var{string} to be used instead of @samp{xx}, while
|
|
+generating output suitable for @command{nroff}, @command{troff} or @TeX{}.
|
|
+
|
|
+@item -O
|
|
+@itemx --format=roff
|
|
+
|
|
+Choose an output format suitable for @command{nroff} or @command{troff}
|
|
+processing. Each output line will look like:
|
|
+
|
|
+@smallexample
|
|
+.xx "@var{tail}" "@var{before}" "@var{keyword_and_after}" "@var{head}" "@var{ref}"
|
|
+@end smallexample
|
|
+
|
|
+so it will be possible to write a @samp{.xx} roff macro to take care of
|
|
+the output typesetting. This is the default output format when @sc{gnu}
|
|
+extensions are disabled. Option @option{-M} can be used to change
|
|
+@samp{xx} to another macro name.
|
|
+
|
|
+In this output format, each non-graphical character, like newline and
|
|
+tab, is merely changed to exactly one space, with no special attempt to
|
|
+compress consecutive spaces. Each quote character: @kbd{"} is doubled
|
|
+so it will be correctly processed by @command{nroff} or @command{troff}.
|
|
+
|
|
+@item -T
|
|
+@itemx --format=tex
|
|
+
|
|
+Choose an output format suitable for @TeX{} processing. Each output
|
|
+line will look like:
|
|
+
|
|
+@smallexample
|
|
+\xx @{@var{tail}@}@{@var{before}@}@{@var{keyword}@}@{@var{after}@}@{@var{head}@}@{@var{ref}@}
|
|
+@end smallexample
|
|
+
|
|
+@noindent
|
|
+so it will be possible to write a @code{\xx} definition to take care of
|
|
+the output typesetting. Note that when references are not being
|
|
+produced, that is, neither option @option{-A} nor option @option{-r} is
|
|
+selected, the last parameter of each @code{\xx} call is inhibited.
|
|
+Option @option{-M} can be used to change @samp{xx} to another macro
|
|
+name.
|
|
+
|
|
+In this output format, some special characters, like @kbd{$}, @kbd{%},
|
|
+@kbd{&}, @kbd{#} and @kbd{_} are automatically protected with a
|
|
+backslash. Curly brackets @kbd{@{}, @kbd{@}} are protected with a
|
|
+backslash and a pair of dollar signs (to force mathematical mode). The
|
|
+backslash itself produces the sequence @code{\backslash@{@}}.
|
|
+Circumflex and tilde diacritical marks produce the sequence @code{^\@{ @}} and
|
|
+@code{~\@{ @}} respectively. Other diacriticized characters of the
|
|
+underlying character set produce an appropriate @TeX{} sequence as far
|
|
+as possible. The other non-graphical characters, like newline and tab,
|
|
+and all other characters which are not part of @acronym{ASCII}, are merely
|
|
+changed to exactly one space, with no special attempt to compress
|
|
+consecutive spaces. Let me know how to improve this special character
|
|
+processing for @TeX{}.
|
|
+
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Compatibility in ptx
|
|
+@subsection The @sc{gnu} extensions to @command{ptx}
|
|
+
|
|
+This version of @command{ptx} contains a few features which do not exist in
|
|
+System V @command{ptx}. These extra features are suppressed by using the
|
|
+@option{-G} command line option, unless overridden by other command line
|
|
+options. Some @sc{gnu} extensions cannot be recovered by overriding, so the
|
|
+simple rule is to avoid @option{-G} if you care about @sc{gnu} extensions.
|
|
+Here are the differences between this program and System V @command{ptx}.
|
|
+
|
|
+@itemize @bullet
|
|
+
|
|
+@item
|
|
+This program can read many input files at once, it always writes the
|
|
+resulting concordance on standard output. On the other hand, System V
|
|
+@command{ptx} reads only one file and sends the result to standard output
|
|
+or, if a second @var{file} parameter is given on the command, to that
|
|
+@var{file}.
|
|
+
|
|
+Having output parameters not introduced by options is a dangerous
|
|
+practice which @sc{gnu} avoids as far as possible. So, for using @command{ptx}
|
|
+portably between @sc{gnu} and System V, you should always use it with a
|
|
+single input file, and always expect the result on standard output. You
|
|
+might also want to automatically configure in a @option{-G} option to
|
|
+@command{ptx} calls in products using @command{ptx}, if the configurator finds
|
|
+that the installed @command{ptx} accepts @option{-G}.
|
|
+
|
|
+@item
|
|
+The only options available in System V @command{ptx} are options @option{-b},
|
|
+@option{-f}, @option{-g}, @option{-i}, @option{-o}, @option{-r}, @option{-t} and
|
|
+@option{-w}. All other options are @sc{gnu} extensions and are not repeated in
|
|
+this enumeration. Moreover, some options have a slightly different
|
|
+meaning when @sc{gnu} extensions are enabled, as explained below.
|
|
+
|
|
+@item
|
|
+By default, concordance output is not formatted for @command{troff} or
|
|
+@command{nroff}. It is rather formatted for a dumb terminal. @command{troff}
|
|
+or @command{nroff} output may still be selected through option @option{-O}.
|
|
+
|
|
+@item
|
|
+Unless @option{-R} option is used, the maximum reference width is
|
|
+subtracted from the total output line width. With @sc{gnu} extensions
|
|
+disabled, width of references is not taken into account in the output
|
|
+line width computations.
|
|
+
|
|
+@item
|
|
+All 256 bytes, even @acronym{ASCII} @sc{nul} bytes, are always read and
|
|
+processed from input file with no adverse effect, even if @sc{gnu} extensions
|
|
+are disabled. However, System V @command{ptx} does not accept 8-bit characters,
|
|
+a few control characters are rejected, and the tilde @kbd{~} is also rejected.
|
|
+
|
|
+@item
|
|
+Input line length is only limited by available memory, even if @sc{gnu}
|
|
+extensions are disabled. However, System V @command{ptx} processes only
|
|
+the first 200 characters in each line.
|
|
+
|
|
+@item
|
|
+The break (non-word) characters default to be every character except all
|
|
+letters of the underlying character set, diacriticized or not. When @sc{gnu}
|
|
+extensions are disabled, the break characters default to space, tab and
|
|
+newline only.
|
|
+
|
|
+@item
|
|
+The program makes better use of output line width. If @sc{gnu} extensions
|
|
+are disabled, the program rather tries to imitate System V @command{ptx},
|
|
+but still, there are some slight disposition glitches this program does
|
|
+not completely reproduce.
|
|
+
|
|
+@item
|
|
+The user can specify both an Ignore file and an Only file. This is not
|
|
+allowed with System V @command{ptx}.
|
|
+
|
|
+@end itemize
|
|
+
|
|
+
|
|
+@node tsort invocation
|
|
+@section @command{tsort}: Topological sort
|
|
+
|
|
+@pindex tsort
|
|
+@cindex topological sort
|
|
+
|
|
+@command{tsort} performs a topological sort on the given @var{file}, or
|
|
+standard input if no input file is given or for a @var{file} of
|
|
+@samp{-}. For more details and some history, see @ref{tsort background}.
|
|
+Synopsis:
|
|
+
|
|
+@example
|
|
+tsort [@var{option}] [@var{file}]
|
|
+@end example
|
|
+
|
|
+@command{tsort} reads its input as pairs of strings, separated by blanks,
|
|
+indicating a partial ordering. The output is a total ordering that
|
|
+corresponds to the given partial ordering.
|
|
+
|
|
+For example
|
|
+
|
|
+@example
|
|
+tsort <<EOF
|
|
+a b c
|
|
+d
|
|
+e f
|
|
+b c d e
|
|
+EOF
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+will produce the output
|
|
+
|
|
+@example
|
|
+a
|
|
+b
|
|
+c
|
|
+d
|
|
+e
|
|
+f
|
|
+@end example
|
|
+
|
|
+Consider a more realistic example.
|
|
+You have a large set of functions all in one file, and they may all be
|
|
+declared static except one. Currently that one (say @code{main}) is the
|
|
+first function defined in the file, and the ones it calls directly follow
|
|
+it, followed by those they call, etc. Let's say that you are determined
|
|
+to take advantage of prototypes, so you have to choose between declaring
|
|
+all of those functions (which means duplicating a lot of information from
|
|
+the definitions) and rearranging the functions so that as many as possible
|
|
+are defined before they are used. One way to automate the latter process
|
|
+is to get a list for each function of the functions it calls directly.
|
|
+Many programs can generate such lists. They describe a call graph.
|
|
+Consider the following list, in which a given line indicates that the
|
|
+function on the left calls the one on the right directly.
|
|
+
|
|
+@example
|
|
+main parse_options
|
|
+main tail_file
|
|
+main tail_forever
|
|
+tail_file pretty_name
|
|
+tail_file write_header
|
|
+tail_file tail
|
|
+tail_forever recheck
|
|
+tail_forever pretty_name
|
|
+tail_forever write_header
|
|
+tail_forever dump_remainder
|
|
+tail tail_lines
|
|
+tail tail_bytes
|
|
+tail_lines start_lines
|
|
+tail_lines dump_remainder
|
|
+tail_lines file_lines
|
|
+tail_lines pipe_lines
|
|
+tail_bytes xlseek
|
|
+tail_bytes start_bytes
|
|
+tail_bytes dump_remainder
|
|
+tail_bytes pipe_bytes
|
|
+file_lines dump_remainder
|
|
+recheck pretty_name
|
|
+@end example
|
|
+
|
|
+then you can use @command{tsort} to produce an ordering of those
|
|
+functions that satisfies your requirement.
|
|
+
|
|
+@example
|
|
+example$ tsort call-graph | tac
|
|
+dump_remainder
|
|
+start_lines
|
|
+file_lines
|
|
+pipe_lines
|
|
+xlseek
|
|
+start_bytes
|
|
+pipe_bytes
|
|
+tail_lines
|
|
+tail_bytes
|
|
+pretty_name
|
|
+write_header
|
|
+tail
|
|
+recheck
|
|
+parse_options
|
|
+tail_file
|
|
+tail_forever
|
|
+main
|
|
+@end example
|
|
+
|
|
+@command{tsort} detects any cycles in the input and writes the first cycle
|
|
+encountered to standard error.
|
|
+
|
|
+Note that for a given partial ordering, generally there is no unique
|
|
+total ordering. In the context of the call graph above, the function
|
|
+@code{parse_options} may be placed anywhere in the list as long as it
|
|
+precedes @code{main}.
|
|
+
|
|
+The only options are @option{--help} and @option{--version}. @xref{Common
|
|
+options}.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+@menu
|
|
+* tsort background:: Where tsort came from.
|
|
+@end menu
|
|
+
|
|
+@node tsort background
|
|
+@subsection @command{tsort}: Background
|
|
+
|
|
+@command{tsort} exists because very early versions of the Unix linker processed
|
|
+an archive file exactly once, and in order. As @command{ld} read each object
|
|
+in the archive, it decided whether it was needed in the program based on
|
|
+whether it defined any symbols which were undefined at that point in
|
|
+the link.
|
|
+
|
|
+This meant that dependencies within the archive had to be handled
|
|
+specially. For example, @code{scanf} probably calls @code{read}. That means
|
|
+that in a single pass through an archive, it was important for @code{scanf.o}
|
|
+to appear before read.o, because otherwise a program which calls
|
|
+@code{scanf} but not @code{read} might end up with an unexpected unresolved
|
|
+reference to @code{read}.
|
|
+
|
|
+The way to address this problem was to first generate a set of
|
|
+dependencies of one object file on another. This was done by a shell
|
|
+script called @command{lorder}. The GNU tools don't provide a version of
|
|
+lorder, as far as I know, but you can still find it in BSD
|
|
+distributions.
|
|
+
|
|
+Then you ran @command{tsort} over the @command{lorder} output, and you used the
|
|
+resulting sort to define the order in which you added objects to the archive.
|
|
+
|
|
+This whole procedure has been obsolete since about 1980, because
|
|
+Unix archives now contain a symbol table (traditionally built by
|
|
+@command{ranlib}, now generally built by @command{ar} itself), and the Unix
|
|
+linker uses the symbol table to effectively make multiple passes over
|
|
+an archive file.
|
|
+
|
|
+Anyhow, that's where tsort came from. To solve an old problem with
|
|
+the way the linker handled archive files, which has since been solved
|
|
+in different ways.
|
|
+
|
|
+
|
|
+@node Operating on fields
|
|
+@chapter Operating on fields
|
|
+
|
|
+@menu
|
|
+* cut invocation:: Print selected parts of lines.
|
|
+* paste invocation:: Merge lines of files.
|
|
+* join invocation:: Join lines on a common field.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node cut invocation
|
|
+@section @command{cut}: Print selected parts of lines
|
|
+
|
|
+@pindex cut
|
|
+@command{cut} writes to standard output selected parts of each line of each
|
|
+input file, or standard input if no files are given or for a file name of
|
|
+@samp{-}. Synopsis:
|
|
+
|
|
+@example
|
|
+cut @var{option}@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+In the table which follows, the @var{byte-list}, @var{character-list},
|
|
+and @var{field-list} are one or more numbers or ranges (two numbers
|
|
+separated by a dash) separated by commas. Bytes, characters, and
|
|
+fields are numbered starting at 1. Incomplete ranges may be
|
|
+given: @option{-@var{m}} means @samp{1-@var{m}}; @samp{@var{n}-} means
|
|
+@samp{@var{n}} through end of line or last field. The list elements
|
|
+can be repeated, can overlap, and can be specified in any order; but
|
|
+the selected input is written in the same order that it is read, and
|
|
+is written exactly once.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common
|
|
+options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -b @var{byte-list}
|
|
+@itemx --bytes=@var{byte-list}
|
|
+@opindex -b
|
|
+@opindex --bytes
|
|
+Select for printing only the bytes in positions listed in
|
|
+@var{byte-list}. Tabs and backspaces are treated like any other
|
|
+character; they take up 1 byte. If an output delimiter is specified,
|
|
+(see the description of @option{--output-delimiter}), then output that
|
|
+string between ranges of selected bytes.
|
|
+
|
|
+@item -c @var{character-list}
|
|
+@itemx --characters=@var{character-list}
|
|
+@opindex -c
|
|
+@opindex --characters
|
|
+Select for printing only the characters in positions listed in
|
|
+@var{character-list}. The same as @option{-b} for now, but
|
|
+internationalization will change that. Tabs and backspaces are
|
|
+treated like any other character; they take up 1 character. If an
|
|
+output delimiter is specified, (see the description of
|
|
+@option{--output-delimiter}), then output that string between ranges
|
|
+of selected bytes.
|
|
+
|
|
+@item -f @var{field-list}
|
|
+@itemx --fields=@var{field-list}
|
|
+@opindex -f
|
|
+@opindex --fields
|
|
+Select for printing only the fields listed in @var{field-list}.
|
|
+Fields are separated by a TAB character by default. Also print any
|
|
+line that contains no delimiter character, unless the
|
|
+@option{--only-delimited} (@option{-s}) option is specified
|
|
+
|
|
+@item -d @var{input_delim_byte}
|
|
+@itemx --delimiter=@var{input_delim_byte}
|
|
+@opindex -d
|
|
+@opindex --delimiter
|
|
+With @option{-f}, use the first byte of @var{input_delim_byte} as
|
|
+the input fields separator (default is TAB).
|
|
+
|
|
+@item -n
|
|
+@opindex -n
|
|
+Do not split multi-byte characters (no-op for now).
|
|
+
|
|
+@item -s
|
|
+@itemx --only-delimited
|
|
+@opindex -s
|
|
+@opindex --only-delimited
|
|
+For @option{-f}, do not print lines that do not contain the field separator
|
|
+character. Normally, any line without a field separator is printed verbatim.
|
|
+
|
|
+@item --output-delimiter=@var{output_delim_string}
|
|
+@opindex --output-delimiter
|
|
+With @option{-f}, output fields are separated by @var{output_delim_string}.
|
|
+The default with @option{-f} is to use the input delimiter.
|
|
+When using @option{-b} or @option{-c} to select ranges of byte or
|
|
+character offsets (as opposed to ranges of fields),
|
|
+output @var{output_delim_string} between non-overlapping
|
|
+ranges of selected bytes.
|
|
+
|
|
+@item --complement
|
|
+@opindex --complement
|
|
+This option is a @acronym{GNU} extension.
|
|
+Select for printing the complement of the bytes, characters or fields
|
|
+selected with the @option{-b}, @option{-c} or @option{-f} options.
|
|
+In other words, do @emph{not} print the bytes, characters or fields
|
|
+specified via those options. This option is useful when you have
|
|
+many fields and want to print all but a few of them.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node paste invocation
|
|
+@section @command{paste}: Merge lines of files
|
|
+
|
|
+@pindex paste
|
|
+@cindex merging files
|
|
+
|
|
+@command{paste} writes to standard output lines consisting of sequentially
|
|
+corresponding lines of each given file, separated by a TAB character.
|
|
+Standard input is used for a file name of @samp{-} or if no input files
|
|
+are given.
|
|
+
|
|
+For example:
|
|
+
|
|
+@example
|
|
+$ cat num2
|
|
+1
|
|
+2
|
|
+$ cat let3
|
|
+a
|
|
+b
|
|
+c
|
|
+$ paste num2 let3
|
|
+1 a
|
|
+2 b
|
|
+ @ c
|
|
+@end example
|
|
+
|
|
+Synopsis:
|
|
+
|
|
+@example
|
|
+paste [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -s
|
|
+@itemx --serial
|
|
+@opindex -s
|
|
+@opindex --serial
|
|
+Paste the lines of one file at a time rather than one line from each
|
|
+file. Using the above example data:
|
|
+
|
|
+@example
|
|
+$ paste -s num2 let3
|
|
+1 2
|
|
+a b c
|
|
+@end example
|
|
+
|
|
+@item -d @var{delim-list}
|
|
+@itemx --delimiters=@var{delim-list}
|
|
+@opindex -d
|
|
+@opindex --delimiters
|
|
+Consecutively use the characters in @var{delim-list} instead of
|
|
+TAB to separate merged lines. When @var{delim-list} is
|
|
+exhausted, start again at its beginning. Using the above example data:
|
|
+
|
|
+@example
|
|
+$ paste -d '%_' num2 let3 num2
|
|
+1%a_1
|
|
+2%b_2
|
|
+%c_
|
|
+@end example
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node join invocation
|
|
+@section @command{join}: Join lines on a common field
|
|
+
|
|
+@pindex join
|
|
+@cindex common field, joining on
|
|
+
|
|
+@command{join} writes to standard output a line for each pair of input
|
|
+lines that have identical join fields. Synopsis:
|
|
+
|
|
+@example
|
|
+join [@var{option}]@dots{} @var{file1} @var{file2}
|
|
+@end example
|
|
+
|
|
+Either @var{file1} or @var{file2} (but not both) can be @samp{-},
|
|
+meaning standard input. @var{file1} and @var{file2} should be
|
|
+sorted on the join fields.
|
|
+
|
|
+@vindex LC_COLLATE
|
|
+Normally, the sort order is that of the
|
|
+collating sequence specified by the @env{LC_COLLATE} locale. Unless
|
|
+the @option{-t} option is given, the sort comparison ignores blanks at
|
|
+the start of the join field, as in @code{sort -b}. If the
|
|
+@option{--ignore-case} option is given, the sort comparison ignores
|
|
+the case of characters in the join field, as in @code{sort -f}.
|
|
+
|
|
+The @command{sort} and @command{join} commands should use consistent
|
|
+locales and options if the output of @command{sort} is fed to
|
|
+@command{join}. You can use a command like @samp{sort -k 1b,1} to
|
|
+sort a file on its default join field, but if you select a non-default
|
|
+locale, join field, separator, or comparison options, then you should
|
|
+do so consistently between @command{join} and @command{sort}.
|
|
+
|
|
+If the input has no unpairable lines, a @acronym{GNU} extension is
|
|
+available; the sort order can be any order that considers two fields
|
|
+to be equal if and only if the sort comparison described above
|
|
+considers them to be equal. For example:
|
|
+
|
|
+@example
|
|
+$ cat file1
|
|
+a a1
|
|
+c c1
|
|
+b b1
|
|
+$ cat file2
|
|
+a a2
|
|
+c c2
|
|
+b b2
|
|
+$ join file1 file2
|
|
+a a1 a2
|
|
+c c1 c2
|
|
+b b1 b2
|
|
+@end example
|
|
+
|
|
+@checkOrderOption{join}
|
|
+
|
|
+The defaults are:
|
|
+@itemize
|
|
+@item the join field is the first field in each line;
|
|
+@item fields in the input are separated by one or more blanks, with leading
|
|
+blanks on the line ignored;
|
|
+@item fields in the output are separated by a space;
|
|
+@item each output line consists of the join field, the remaining
|
|
+fields from @var{file1}, then the remaining fields from @var{file2}.
|
|
+@end itemize
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -a @var{file-number}
|
|
+@opindex -a
|
|
+Print a line for each unpairable line in file @var{file-number} (either
|
|
+@samp{1} or @samp{2}), in addition to the normal output.
|
|
+
|
|
+@item --check-order
|
|
+Fail with an error message if either input file is wrongly ordered.
|
|
+
|
|
+@item --nocheck-order
|
|
+Do not check that both input files are in sorted order. This is the default.
|
|
+
|
|
+@item -e @var{string}
|
|
+@opindex -e
|
|
+Replace those output fields that are missing in the input with
|
|
+@var{string}.
|
|
+
|
|
+@item -i
|
|
+@itemx --ignore-case
|
|
+@opindex -i
|
|
+@opindex --ignore-case
|
|
+Ignore differences in case when comparing keys.
|
|
+With this option, the lines of the input files must be ordered in the same way.
|
|
+Use @samp{sort -f} to produce this ordering.
|
|
+
|
|
+@item -1 @var{field}
|
|
+@opindex -1
|
|
+Join on field @var{field} (a positive integer) of file 1.
|
|
+
|
|
+@item -2 @var{field}
|
|
+@opindex -2
|
|
+Join on field @var{field} (a positive integer) of file 2.
|
|
+
|
|
+@item -j @var{field}
|
|
+Equivalent to @option{-1 @var{field} -2 @var{field}}.
|
|
+
|
|
+@item -o @var{field-list}
|
|
+Construct each output line according to the format in @var{field-list}.
|
|
+Each element in @var{field-list} is either the single character @samp{0} or
|
|
+has the form @var{m.n} where the file number, @var{m}, is @samp{1} or
|
|
+@samp{2} and @var{n} is a positive field number.
|
|
+
|
|
+A field specification of @samp{0} denotes the join field.
|
|
+In most cases, the functionality of the @samp{0} field spec
|
|
+may be reproduced using the explicit @var{m.n} that corresponds
|
|
+to the join field. However, when printing unpairable lines
|
|
+(using either of the @option{-a} or @option{-v} options), there is no way
|
|
+to specify the join field using @var{m.n} in @var{field-list}
|
|
+if there are unpairable lines in both files.
|
|
+To give @command{join} that functionality, @acronym{POSIX} invented the @samp{0}
|
|
+field specification notation.
|
|
+
|
|
+The elements in @var{field-list}
|
|
+are separated by commas or blanks.
|
|
+Blank separators typically need to be quoted for the shell. For
|
|
+example, the commands @samp{join -o 1.2,2.2} and @samp{join -o '1.2
|
|
+2.2'} are equivalent.
|
|
+
|
|
+All output lines---including those printed because of any -a or -v
|
|
+option---are subject to the specified @var{field-list}.
|
|
+
|
|
+@item -t @var{char}
|
|
+Use character @var{char} as the input and output field separator.
|
|
+Treat as significant each occurrence of @var{char} in the input file.
|
|
+Use @samp{sort -t @var{char}}, without the @option{-b} option of
|
|
+@samp{sort}, to produce this ordering.
|
|
+
|
|
+@item -v @var{file-number}
|
|
+Print a line for each unpairable line in file @var{file-number}
|
|
+(either @samp{1} or @samp{2}), instead of the normal output.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node Operating on characters
|
|
+@chapter Operating on characters
|
|
+
|
|
+@cindex operating on characters
|
|
+
|
|
+This commands operate on individual characters.
|
|
+
|
|
+@menu
|
|
+* tr invocation:: Translate, squeeze, and/or delete characters.
|
|
+* expand invocation:: Convert tabs to spaces.
|
|
+* unexpand invocation:: Convert spaces to tabs.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node tr invocation
|
|
+@section @command{tr}: Translate, squeeze, and/or delete characters
|
|
+
|
|
+@pindex tr
|
|
+
|
|
+Synopsis:
|
|
+
|
|
+@example
|
|
+tr [@var{option}]@dots{} @var{set1} [@var{set2}]
|
|
+@end example
|
|
+
|
|
+@command{tr} copies standard input to standard output, performing
|
|
+one of the following operations:
|
|
+
|
|
+@itemize @bullet
|
|
+@item
|
|
+translate, and optionally squeeze repeated characters in the result,
|
|
+@item
|
|
+squeeze repeated characters,
|
|
+@item
|
|
+delete characters,
|
|
+@item
|
|
+delete characters, then squeeze repeated characters from the result.
|
|
+@end itemize
|
|
+
|
|
+The @var{set1} and (if given) @var{set2} arguments define ordered
|
|
+sets of characters, referred to below as @var{set1} and @var{set2}. These
|
|
+sets are the characters of the input that @command{tr} operates on.
|
|
+The @option{--complement} (@option{-c}, @option{-C}) option replaces
|
|
+@var{set1} with its
|
|
+complement (all of the characters that are not in @var{set1}).
|
|
+
|
|
+Currently @command{tr} fully supports only single-byte characters.
|
|
+Eventually it will support multibyte characters; when it does, the
|
|
+@option{-C} option will cause it to complement the set of characters,
|
|
+whereas @option{-c} will cause it to complement the set of values.
|
|
+This distinction will matter only when some values are not characters,
|
|
+and this is possible only in locales using multibyte encodings when
|
|
+the input contains encoding errors.
|
|
+
|
|
+The program accepts the @option{--help} and @option{--version}
|
|
+options. @xref{Common options}. Options must precede operands.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+@menu
|
|
+* Character sets:: Specifying sets of characters.
|
|
+* Translating:: Changing one set of characters to another.
|
|
+* Squeezing:: Squeezing repeats and deleting.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node Character sets
|
|
+@subsection Specifying sets of characters
|
|
+
|
|
+@cindex specifying sets of characters
|
|
+
|
|
+The format of the @var{set1} and @var{set2} arguments resembles
|
|
+the format of regular expressions; however, they are not regular
|
|
+expressions, only lists of characters. Most characters simply
|
|
+represent themselves in these strings, but the strings can contain
|
|
+the shorthands listed below, for convenience. Some of them can be
|
|
+used only in @var{set1} or @var{set2}, as noted below.
|
|
+
|
|
+@table @asis
|
|
+
|
|
+@item Backslash escapes
|
|
+@cindex backslash escapes
|
|
+
|
|
+The following backslash escape sequences are recognized:
|
|
+
|
|
+@table @samp
|
|
+@item \a
|
|
+Control-G.
|
|
+@item \b
|
|
+Control-H.
|
|
+@item \f
|
|
+Control-L.
|
|
+@item \n
|
|
+Control-J.
|
|
+@item \r
|
|
+Control-M.
|
|
+@item \t
|
|
+Control-I.
|
|
+@item \v
|
|
+Control-K.
|
|
+@item \@var{ooo}
|
|
+The character with the value given by @var{ooo}, which is 1 to 3
|
|
+octal digits,
|
|
+@item \\
|
|
+A backslash.
|
|
+@end table
|
|
+
|
|
+While a backslash followed by a character not listed above is
|
|
+interpreted as that character, the backslash also effectively
|
|
+removes any special significance, so it is useful to escape
|
|
+@samp{[}, @samp{]}, @samp{*}, and @samp{-}.
|
|
+
|
|
+@item Ranges
|
|
+@cindex ranges
|
|
+
|
|
+The notation @samp{@var{m}-@var{n}} expands to all of the characters
|
|
+from @var{m} through @var{n}, in ascending order. @var{m} should
|
|
+collate before @var{n}; if it doesn't, an error results. As an example,
|
|
+@samp{0-9} is the same as @samp{0123456789}.
|
|
+
|
|
+@sc{gnu} @command{tr} does not support the System V syntax that uses square
|
|
+brackets to enclose ranges. Translations specified in that format
|
|
+sometimes work as expected, since the brackets are often transliterated
|
|
+to themselves. However, they should be avoided because they sometimes
|
|
+behave unexpectedly. For example, @samp{tr -d '[0-9]'} deletes brackets
|
|
+as well as digits.
|
|
+
|
|
+Many historically common and even accepted uses of ranges are not
|
|
+portable. For example, on @acronym{EBCDIC} hosts using the @samp{A-Z}
|
|
+range will not do what most would expect because @samp{A} through @samp{Z}
|
|
+are not contiguous as they are in @acronym{ASCII}.
|
|
+If you can rely on a @acronym{POSIX} compliant version of @command{tr}, then
|
|
+the best way to work around this is to use character classes (see below).
|
|
+Otherwise, it is most portable (and most ugly) to enumerate the members
|
|
+of the ranges.
|
|
+
|
|
+@item Repeated characters
|
|
+@cindex repeated characters
|
|
+
|
|
+The notation @samp{[@var{c}*@var{n}]} in @var{set2} expands to @var{n}
|
|
+copies of character @var{c}. Thus, @samp{[y*6]} is the same as
|
|
+@samp{yyyyyy}. The notation @samp{[@var{c}*]} in @var{string2} expands
|
|
+to as many copies of @var{c} as are needed to make @var{set2} as long as
|
|
+@var{set1}. If @var{n} begins with @samp{0}, it is interpreted in
|
|
+octal, otherwise in decimal.
|
|
+
|
|
+@item Character classes
|
|
+@cindex character classes
|
|
+
|
|
+The notation @samp{[:@var{class}:]} expands to all of the characters in
|
|
+the (predefined) class @var{class}. The characters expand in no
|
|
+particular order, except for the @code{upper} and @code{lower} classes,
|
|
+which expand in ascending order. When the @option{--delete} (@option{-d})
|
|
+and @option{--squeeze-repeats} (@option{-s}) options are both given, any
|
|
+character class can be used in @var{set2}. Otherwise, only the
|
|
+character classes @code{lower} and @code{upper} are accepted in
|
|
+@var{set2}, and then only if the corresponding character class
|
|
+(@code{upper} and @code{lower}, respectively) is specified in the same
|
|
+relative position in @var{set1}. Doing this specifies case conversion.
|
|
+The class names are given below; an error results when an invalid class
|
|
+name is given.
|
|
+
|
|
+@table @code
|
|
+@item alnum
|
|
+@opindex alnum
|
|
+Letters and digits.
|
|
+@item alpha
|
|
+@opindex alpha
|
|
+Letters.
|
|
+@item blank
|
|
+@opindex blank
|
|
+Horizontal whitespace.
|
|
+@item cntrl
|
|
+@opindex cntrl
|
|
+Control characters.
|
|
+@item digit
|
|
+@opindex digit
|
|
+Digits.
|
|
+@item graph
|
|
+@opindex graph
|
|
+Printable characters, not including space.
|
|
+@item lower
|
|
+@opindex lower
|
|
+Lowercase letters.
|
|
+@item print
|
|
+@opindex print
|
|
+Printable characters, including space.
|
|
+@item punct
|
|
+@opindex punct
|
|
+Punctuation characters.
|
|
+@item space
|
|
+@opindex space
|
|
+Horizontal or vertical whitespace.
|
|
+@item upper
|
|
+@opindex upper
|
|
+Uppercase letters.
|
|
+@item xdigit
|
|
+@opindex xdigit
|
|
+Hexadecimal digits.
|
|
+@end table
|
|
+
|
|
+@item Equivalence classes
|
|
+@cindex equivalence classes
|
|
+
|
|
+The syntax @samp{[=@var{c}=]} expands to all of the characters that are
|
|
+equivalent to @var{c}, in no particular order. Equivalence classes are
|
|
+a relatively recent invention intended to support non-English alphabets.
|
|
+But there seems to be no standard way to define them or determine their
|
|
+contents. Therefore, they are not fully implemented in @sc{gnu} @command{tr};
|
|
+each character's equivalence class consists only of that character,
|
|
+which is of no particular use.
|
|
+
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Translating
|
|
+@subsection Translating
|
|
+
|
|
+@cindex translating characters
|
|
+
|
|
+@command{tr} performs translation when @var{set1} and @var{set2} are
|
|
+both given and the @option{--delete} (@option{-d}) option is not given.
|
|
+@command{tr} translates each character of its input that is in @var{set1}
|
|
+to the corresponding character in @var{set2}. Characters not in
|
|
+@var{set1} are passed through unchanged. When a character appears more
|
|
+than once in @var{set1} and the corresponding characters in @var{set2}
|
|
+are not all the same, only the final one is used. For example, these
|
|
+two commands are equivalent:
|
|
+
|
|
+@example
|
|
+tr aaa xyz
|
|
+tr a z
|
|
+@end example
|
|
+
|
|
+A common use of @command{tr} is to convert lowercase characters to
|
|
+uppercase. This can be done in many ways. Here are three of them:
|
|
+
|
|
+@example
|
|
+tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
|
|
+tr a-z A-Z
|
|
+tr '[:lower:]' '[:upper:]'
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+But note that using ranges like @code{a-z} above is not portable.
|
|
+
|
|
+When @command{tr} is performing translation, @var{set1} and @var{set2}
|
|
+typically have the same length. If @var{set1} is shorter than
|
|
+@var{set2}, the extra characters at the end of @var{set2} are ignored.
|
|
+
|
|
+On the other hand, making @var{set1} longer than @var{set2} is not
|
|
+portable; @acronym{POSIX} says that the result is undefined. In this situation,
|
|
+BSD @command{tr} pads @var{set2} to the length of @var{set1} by repeating
|
|
+the last character of @var{set2} as many times as necessary. System V
|
|
+@command{tr} truncates @var{set1} to the length of @var{set2}.
|
|
+
|
|
+By default, @sc{gnu} @command{tr} handles this case like BSD @command{tr}.
|
|
+When the @option{--truncate-set1} (@option{-t}) option is given,
|
|
+@sc{gnu} @command{tr} handles this case like the System V @command{tr}
|
|
+instead. This option is ignored for operations other than translation.
|
|
+
|
|
+Acting like System V @command{tr} in this case breaks the relatively common
|
|
+BSD idiom:
|
|
+
|
|
+@example
|
|
+tr -cs A-Za-z0-9 '\012'
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+because it converts only zero bytes (the first element in the
|
|
+complement of @var{set1}), rather than all non-alphanumerics, to
|
|
+newlines.
|
|
+
|
|
+@noindent
|
|
+By the way, the above idiom is not portable because it uses ranges, and
|
|
+it assumes that the octal code for newline is 012.
|
|
+Assuming a @acronym{POSIX} compliant @command{tr}, here is a better way to write it:
|
|
+
|
|
+@example
|
|
+tr -cs '[:alnum:]' '[\n*]'
|
|
+@end example
|
|
+
|
|
+
|
|
+@node Squeezing
|
|
+@subsection Squeezing repeats and deleting
|
|
+
|
|
+@cindex squeezing repeat characters
|
|
+@cindex deleting characters
|
|
+
|
|
+When given just the @option{--delete} (@option{-d}) option, @command{tr}
|
|
+removes any input characters that are in @var{set1}.
|
|
+
|
|
+When given just the @option{--squeeze-repeats} (@option{-s}) option,
|
|
+@command{tr} replaces each input sequence of a repeated character that
|
|
+is in @var{set1} with a single occurrence of that character.
|
|
+
|
|
+When given both @option{--delete} and @option{--squeeze-repeats}, @command{tr}
|
|
+first performs any deletions using @var{set1}, then squeezes repeats
|
|
+from any remaining characters using @var{set2}.
|
|
+
|
|
+The @option{--squeeze-repeats} option may also be used when translating,
|
|
+in which case @command{tr} first performs translation, then squeezes
|
|
+repeats from any remaining characters using @var{set2}.
|
|
+
|
|
+Here are some examples to illustrate various combinations of options:
|
|
+
|
|
+@itemize @bullet
|
|
+
|
|
+@item
|
|
+Remove all zero bytes:
|
|
+
|
|
+@example
|
|
+tr -d '\0'
|
|
+@end example
|
|
+
|
|
+@item
|
|
+Put all words on lines by themselves. This converts all
|
|
+non-alphanumeric characters to newlines, then squeezes each string
|
|
+of repeated newlines into a single newline:
|
|
+
|
|
+@example
|
|
+tr -cs '[:alnum:]' '[\n*]'
|
|
+@end example
|
|
+
|
|
+@item
|
|
+Convert each sequence of repeated newlines to a single newline:
|
|
+
|
|
+@example
|
|
+tr -s '\n'
|
|
+@end example
|
|
+
|
|
+@item
|
|
+Find doubled occurrences of words in a document.
|
|
+@c Separate the following two "the"s, so typo checkers don't complain.
|
|
+For example, people often write ``the @w{}the'' with the repeated words
|
|
+separated by a newline. The Bourne shell script below works first
|
|
+by converting each sequence of punctuation and blank characters to a
|
|
+single newline. That puts each ``word'' on a line by itself.
|
|
+Next it maps all uppercase characters to lower case, and finally it
|
|
+runs @command{uniq} with the @option{-d} option to print out only the words
|
|
+that were repeated.
|
|
+
|
|
+@example
|
|
+#!/bin/sh
|
|
+cat -- "$@@" \
|
|
+ | tr -s '[:punct:][:blank:]' '[\n*]' \
|
|
+ | tr '[:upper:]' '[:lower:]' \
|
|
+ | uniq -d
|
|
+@end example
|
|
+
|
|
+@item
|
|
+Deleting a small set of characters is usually straightforward. For example,
|
|
+to remove all @samp{a}s, @samp{x}s, and @samp{M}s you would do this:
|
|
+
|
|
+@example
|
|
+tr -d axM
|
|
+@end example
|
|
+
|
|
+However, when @samp{-} is one of those characters, it can be tricky because
|
|
+@samp{-} has special meanings. Performing the same task as above but also
|
|
+removing all @samp{-} characters, we might try @code{tr -d -axM}, but
|
|
+that would fail because @command{tr} would try to interpret @option{-a} as
|
|
+a command-line option. Alternatively, we could try putting the hyphen
|
|
+inside the string, @code{tr -d a-xM}, but that wouldn't work either because
|
|
+it would make @command{tr} interpret @code{a-x} as the range of characters
|
|
+@samp{a}@dots{}@samp{x} rather than the three.
|
|
+One way to solve the problem is to put the hyphen at the end of the list
|
|
+of characters:
|
|
+
|
|
+@example
|
|
+tr -d axM-
|
|
+@end example
|
|
+
|
|
+Or you can use @samp{--} to terminate option processing:
|
|
+
|
|
+@example
|
|
+tr -d -- -axM
|
|
+@end example
|
|
+
|
|
+More generally, use the character class notation @code{[=c=]}
|
|
+with @samp{-} (or any other character) in place of the @samp{c}:
|
|
+
|
|
+@example
|
|
+tr -d '[=-=]axM'
|
|
+@end example
|
|
+
|
|
+Note how single quotes are used in the above example to protect the
|
|
+square brackets from interpretation by a shell.
|
|
+
|
|
+@end itemize
|
|
+
|
|
+
|
|
+@node expand invocation
|
|
+@section @command{expand}: Convert tabs to spaces
|
|
+
|
|
+@pindex expand
|
|
+@cindex tabs to spaces, converting
|
|
+@cindex converting tabs to spaces
|
|
+
|
|
+@command{expand} writes the contents of each given @var{file}, or standard
|
|
+input if none are given or for a @var{file} of @samp{-}, to standard
|
|
+output, with tab characters converted to the appropriate number of
|
|
+spaces. Synopsis:
|
|
+
|
|
+@example
|
|
+expand [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+By default, @command{expand} converts all tabs to spaces. It preserves
|
|
+backspace characters in the output; they decrement the column count for
|
|
+tab calculations. The default action is equivalent to @option{-t 8} (set
|
|
+tabs every 8 columns).
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -t @var{tab1}[,@var{tab2}]@dots{}
|
|
+@itemx --tabs=@var{tab1}[,@var{tab2}]@dots{}
|
|
+@opindex -t
|
|
+@opindex --tabs
|
|
+@cindex tab stops, setting
|
|
+If only one tab stop is given, set the tabs @var{tab1} spaces apart
|
|
+(default is 8). Otherwise, set the tabs at columns @var{tab1},
|
|
+@var{tab2}, @dots{} (numbered from 0), and replace any tabs beyond the
|
|
+last tab stop given with single spaces. Tab stops can be separated by
|
|
+blanks as well as by commas.
|
|
+
|
|
+For compatibility, GNU @command{expand} also accepts the obsolete
|
|
+option syntax, @option{-@var{t1}[,@var{t2}]@dots{}}. New scripts
|
|
+should use @option{-t @var{t1}[,@var{t2}]@dots{}} instead.
|
|
+
|
|
+@item -i
|
|
+@itemx --initial
|
|
+@opindex -i
|
|
+@opindex --initial
|
|
+@cindex initial tabs, converting
|
|
+Only convert initial tabs (those that precede all non-space or non-tab
|
|
+characters) on each line to spaces.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node unexpand invocation
|
|
+@section @command{unexpand}: Convert spaces to tabs
|
|
+
|
|
+@pindex unexpand
|
|
+
|
|
+@command{unexpand} writes the contents of each given @var{file}, or
|
|
+standard input if none are given or for a @var{file} of @samp{-}, to
|
|
+standard output, converting blanks at the beginning of each line into
|
|
+as many tab characters as needed. In the default @acronym{POSIX}
|
|
+locale, a @dfn{blank} is a space or a tab; other locales may specify
|
|
+additional blank characters. Synopsis:
|
|
+
|
|
+@example
|
|
+unexpand [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+By default, @command{unexpand} converts only initial blanks (those
|
|
+that precede all non-blank characters) on each line. It
|
|
+preserves backspace characters in the output; they decrement the column
|
|
+count for tab calculations. By default, tabs are set at every 8th
|
|
+column.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -t @var{tab1}[,@var{tab2}]@dots{}
|
|
+@itemx --tabs=@var{tab1}[,@var{tab2}]@dots{}
|
|
+@opindex -t
|
|
+@opindex --tabs
|
|
+If only one tab stop is given, set the tabs @var{tab1} columns apart
|
|
+instead of the default 8. Otherwise, set the tabs at columns
|
|
+@var{tab1}, @var{tab2}, @dots{} (numbered from 0), and leave blanks
|
|
+beyond the tab stops given unchanged. Tab stops can be separated by
|
|
+blanks as well as by commas. This option implies the @option{-a} option.
|
|
+
|
|
+For compatibility, GNU @command{unexpand} supports the obsolete option syntax,
|
|
+@option{-@var{tab1}[,@var{tab2}]@dots{}}, where tab stops must be
|
|
+separated by commas. (Unlike @option{-t}, this obsolete option does
|
|
+not imply @option{-a}.) New scripts should use @option{--first-only -t
|
|
+@var{tab1}[,@var{tab2}]@dots{}} instead.
|
|
+
|
|
+@item -a
|
|
+@itemx --all
|
|
+@opindex -a
|
|
+@opindex --all
|
|
+Also convert all sequences of two or more blanks just before a tab stop,
|
|
+even if they occur after non-blank characters in a line.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node Directory listing
|
|
+@chapter Directory listing
|
|
+
|
|
+This chapter describes the @command{ls} command and its variants @command{dir}
|
|
+and @command{vdir}, which list information about files.
|
|
+
|
|
+@menu
|
|
+* ls invocation:: List directory contents.
|
|
+* dir invocation:: Briefly ls.
|
|
+* vdir invocation:: Verbosely ls.
|
|
+* dircolors invocation:: Color setup for ls, etc.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node ls invocation
|
|
+@section @command{ls}: List directory contents
|
|
+
|
|
+@pindex ls
|
|
+@cindex directory listing
|
|
+
|
|
+The @command{ls} program lists information about files (of any type,
|
|
+including directories). Options and file arguments can be intermixed
|
|
+arbitrarily, as usual.
|
|
+
|
|
+For non-option command-line arguments that are directories, by default
|
|
+@command{ls} lists the contents of directories, not recursively, and
|
|
+omitting files with names beginning with @samp{.}. For other non-option
|
|
+arguments, by default @command{ls} lists just the file name. If no
|
|
+non-option argument is specified, @command{ls} operates on the current
|
|
+directory, acting as if it had been invoked with a single argument of @samp{.}.
|
|
+
|
|
+@vindex LC_ALL
|
|
+By default, the output is sorted alphabetically, according to the locale
|
|
+settings in effect.@footnote{If you use a non-@acronym{POSIX}
|
|
+locale (e.g., by setting @env{LC_ALL} to @samp{en_US}), then @command{ls} may
|
|
+produce output that is sorted differently than you're accustomed to.
|
|
+In that case, set the @env{LC_ALL} environment variable to @samp{C}.}
|
|
+If standard output is
|
|
+a terminal, the output is in columns (sorted vertically) and control
|
|
+characters are output as question marks; otherwise, the output is listed
|
|
+one per line and control characters are output as-is.
|
|
+
|
|
+Because @command{ls} is such a fundamental program, it has accumulated many
|
|
+options over the years. They are described in the subsections below;
|
|
+within each section, options are listed alphabetically (ignoring case).
|
|
+The division of options into the subsections is not absolute, since some
|
|
+options affect more than one aspect of @command{ls}'s operation.
|
|
+
|
|
+@cindex exit status of @command{ls}
|
|
+Exit status:
|
|
+
|
|
+@display
|
|
+0 success
|
|
+1 minor problems (e.g., failure to access a file or directory not
|
|
+ specified as a command line argument. This happens when listing a
|
|
+ directory in which entries are actively being removed or renamed.)
|
|
+2 serious trouble (e.g., memory exhausted, invalid option, failure
|
|
+ to access a file or directory specified as a command line argument
|
|
+ or a directory loop)
|
|
+@end display
|
|
+
|
|
+Also see @ref{Common options}.
|
|
+
|
|
+@menu
|
|
+* Which files are listed::
|
|
+* What information is listed::
|
|
+* Sorting the output::
|
|
+* Details about version sort::
|
|
+* General output formatting::
|
|
+* Formatting file timestamps::
|
|
+* Formatting the file names::
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node Which files are listed
|
|
+@subsection Which files are listed
|
|
+
|
|
+These options determine which files @command{ls} lists information for.
|
|
+By default, @command{ls} lists files and the contents of any
|
|
+directories on the command line, except that in directories it ignores
|
|
+files whose names start with @samp{.}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -a
|
|
+@itemx --all
|
|
+@opindex -a
|
|
+@opindex --all
|
|
+In directories, do not ignore file names that start with @samp{.}.
|
|
+
|
|
+@item -A
|
|
+@itemx --almost-all
|
|
+@opindex -A
|
|
+@opindex --almost-all
|
|
+In directories, do not ignore all file names that start with @samp{.};
|
|
+ignore only @file{.} and @file{..}. The @option{--all} (@option{-a})
|
|
+option overrides this option.
|
|
+
|
|
+@item -B
|
|
+@itemx --ignore-backups
|
|
+@opindex -B
|
|
+@opindex --ignore-backups
|
|
+@cindex backup files, ignoring
|
|
+In directories, ignore files that end with @samp{~}. This option is
|
|
+equivalent to @samp{--ignore='*~' --ignore='.*~'}.
|
|
+
|
|
+@item -d
|
|
+@itemx --directory
|
|
+@opindex -d
|
|
+@opindex --directory
|
|
+List just the names of directories, as with other types of files, rather
|
|
+than listing their contents.
|
|
+@c The following sentence is the same as the one for -F.
|
|
+Do not follow symbolic links listed on the
|
|
+command line unless the @option{--dereference-command-line} (@option{-H}),
|
|
+@option{--dereference} (@option{-L}), or
|
|
+@option{--dereference-command-line-symlink-to-dir} options are specified.
|
|
+
|
|
+@item -H
|
|
+@itemx --dereference-command-line
|
|
+@opindex -H
|
|
+@opindex --dereference-command-line
|
|
+@cindex symbolic links, dereferencing
|
|
+If a command line argument specifies a symbolic link, show information
|
|
+for the file the link references rather than for the link itself.
|
|
+
|
|
+@itemx --dereference-command-line-symlink-to-dir
|
|
+@opindex --dereference-command-line-symlink-to-dir
|
|
+@cindex symbolic links, dereferencing
|
|
+Do not dereference symbolic links, with one exception:
|
|
+if a command line argument specifies a symbolic link that refers to
|
|
+a directory, show information for that directory rather than for the
|
|
+link itself.
|
|
+This is the default behavior when no other dereferencing-related
|
|
+option has been specified (@option{--classify} (@option{-F}),
|
|
+@option{--directory} (@option{-d}),
|
|
+(@option{-l}),
|
|
+@option{--dereference} (@option{-L}), or
|
|
+@option{--dereference-command-line} (@option{-H})).
|
|
+
|
|
+@item --group-directories-first
|
|
+@opindex --group-directories-first
|
|
+Group all the directories before the files and then sort the
|
|
+directories and the files separately using the selected sort key
|
|
+(see --sort option).
|
|
+That is, this option specifies a primary sort key,
|
|
+and the --sort option specifies a secondary key.
|
|
+However, any use of @option{--sort=none}
|
|
+(@option{-U}) disables this option altogether.
|
|
+
|
|
+@item --hide=PATTERN
|
|
+@opindex --hide=@var{pattern}
|
|
+In directories, ignore files whose names match the shell pattern
|
|
+@var{pattern}, unless the @option{--all} (@option{-a}) or
|
|
+@option{--almost-all} (@option{-A}) is also given. This
|
|
+option acts like @option{--ignore=@var{pattern}} except that it has no
|
|
+effect if @option{--all} (@option{-a}) or @option{--almost-all}
|
|
+(@option{-A}) is also given.
|
|
+
|
|
+This option can be useful in shell aliases. For example, if
|
|
+@command{lx} is an alias for @samp{ls --hide='*~'} and @command{ly} is
|
|
+an alias for @samp{ls --ignore='*~'}, then the command @samp{lx -A}
|
|
+lists the file @file{README~} even though @samp{ly -A} would not.
|
|
+
|
|
+@item -I @var{pattern}
|
|
+@itemx --ignore=@var{pattern}
|
|
+@opindex -I
|
|
+@opindex --ignore=@var{pattern}
|
|
+In directories, ignore files whose names match the shell pattern
|
|
+(not regular expression) @var{pattern}. As
|
|
+in the shell, an initial @samp{.} in a file name does not match a
|
|
+wildcard at the start of @var{pattern}. Sometimes it is useful
|
|
+to give this option several times. For example,
|
|
+
|
|
+@smallexample
|
|
+$ ls --ignore='.??*' --ignore='.[^.]' --ignore='#*'
|
|
+@end smallexample
|
|
+
|
|
+The first option ignores names of length 3 or more that start with @samp{.},
|
|
+the second ignores all two-character names that start with @samp{.}
|
|
+except @samp{..}, and the third ignores names that start with @samp{#}.
|
|
+
|
|
+@item -L
|
|
+@itemx --dereference
|
|
+@opindex -L
|
|
+@opindex --dereference
|
|
+@cindex symbolic links, dereferencing
|
|
+When showing file information for a symbolic link, show information
|
|
+for the file the link references rather than the link itself.
|
|
+However, even with this option, @command{ls} still prints the name
|
|
+of the link itself, not the name of the file that the link points to.
|
|
+
|
|
+@item -R
|
|
+@itemx --recursive
|
|
+@opindex -R
|
|
+@opindex --recursive
|
|
+@cindex recursive directory listing
|
|
+@cindex directory listing, recursive
|
|
+List the contents of all directories recursively.
|
|
+
|
|
+@end table
|
|
+
|
|
+
|
|
+@node What information is listed
|
|
+@subsection What information is listed
|
|
+
|
|
+These options affect the information that @command{ls} displays. By
|
|
+default, only file names are shown.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item --author
|
|
+@opindex --author
|
|
+@cindex hurd, author, printing
|
|
+List each file's author when producing long format directory listings.
|
|
+In GNU/Hurd, file authors can differ from their owners, but in other
|
|
+operating systems the two are the same.
|
|
+
|
|
+@item -D
|
|
+@itemx --dired
|
|
+@opindex -D
|
|
+@opindex --dired
|
|
+@cindex dired Emacs mode support
|
|
+With the long listing (@option{-l}) format, print an additional line after
|
|
+the main output:
|
|
+
|
|
+@example
|
|
+//DIRED// @var{beg1} @var{end1} @var{beg2} @var{end2} @dots{}
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+The @var{begn} and @var{endn} are unsigned integers that record the
|
|
+byte position of the beginning and end of each file name in the output.
|
|
+This makes it easy for Emacs to find the names, even when they contain
|
|
+unusual characters such as space or newline, without fancy searching.
|
|
+
|
|
+If directories are being listed recursively (@option{-R}), output a similar
|
|
+line with offsets for each subdirectory name:
|
|
+
|
|
+@example
|
|
+//SUBDIRED// @var{beg1} @var{end1} @dots{}
|
|
+@end example
|
|
+
|
|
+Finally, output a line of the form:
|
|
+
|
|
+@example
|
|
+//DIRED-OPTIONS// --quoting-style=@var{word}
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+where @var{word} is the quoting style (@pxref{Formatting the file names}).
|
|
+
|
|
+Here is an actual example:
|
|
+
|
|
+@example
|
|
+$ mkdir -p a/sub/deeper a/sub2
|
|
+$ touch a/f1 a/f2
|
|
+$ touch a/sub/deeper/file
|
|
+$ ls -gloRF --dired a
|
|
+ a:
|
|
+ total 8
|
|
+ -rw-r--r-- 1 0 Jun 10 12:27 f1
|
|
+ -rw-r--r-- 1 0 Jun 10 12:27 f2
|
|
+ drwxr-xr-x 3 4096 Jun 10 12:27 sub/
|
|
+ drwxr-xr-x 2 4096 Jun 10 12:27 sub2/
|
|
+
|
|
+ a/sub:
|
|
+ total 4
|
|
+ drwxr-xr-x 2 4096 Jun 10 12:27 deeper/
|
|
+
|
|
+ a/sub/deeper:
|
|
+ total 0
|
|
+ -rw-r--r-- 1 0 Jun 10 12:27 file
|
|
+
|
|
+ a/sub2:
|
|
+ total 0
|
|
+//DIRED// 48 50 84 86 120 123 158 162 217 223 282 286
|
|
+//SUBDIRED// 2 3 167 172 228 240 290 296
|
|
+//DIRED-OPTIONS// --quoting-style=literal
|
|
+@end example
|
|
+
|
|
+Note that the pairs of offsets on the @samp{//DIRED//} line above delimit
|
|
+these names: @file{f1}, @file{f2}, @file{sub}, @file{sub2}, @file{deeper},
|
|
+@file{file}.
|
|
+The offsets on the @samp{//SUBDIRED//} line delimit the following
|
|
+directory names: @file{a}, @file{a/sub}, @file{a/sub/deeper}, @file{a/sub2}.
|
|
+
|
|
+Here is an example of how to extract the fifth entry name, @samp{deeper},
|
|
+corresponding to the pair of offsets, 222 and 228:
|
|
+
|
|
+@example
|
|
+$ ls -gloRF --dired a > out
|
|
+$ dd bs=1 skip=222 count=6 < out 2>/dev/null; echo
|
|
+deeper
|
|
+@end example
|
|
+
|
|
+Note that although the listing above includes a trailing slash
|
|
+for the @samp{deeper} entry, the offsets select the name without
|
|
+the trailing slash. However, if you invoke @command{ls} with @option{--dired}
|
|
+along with an option like @option{--escape} (aka @option{-b}) and operate
|
|
+on a file whose name contains special characters, notice that the backslash
|
|
+@emph{is} included:
|
|
+
|
|
+@example
|
|
+$ touch 'a b'
|
|
+$ ls -blog --dired 'a b'
|
|
+ -rw-r--r-- 1 0 Jun 10 12:28 a\ b
|
|
+//DIRED// 30 34
|
|
+//DIRED-OPTIONS// --quoting-style=escape
|
|
+@end example
|
|
+
|
|
+If you use a quoting style that adds quote marks
|
|
+(e.g., @option{--quoting-style=c}), then the offsets include the quote marks.
|
|
+So beware that the user may select the quoting style via the environment
|
|
+variable @env{QUOTING_STYLE}. Hence, applications using @option{--dired}
|
|
+should either specify an explicit @option{--quoting-style=literal} option
|
|
+(aka @option{-N} or @option{--literal}) on the command line, or else be
|
|
+prepared to parse the escaped names.
|
|
+
|
|
+@item --full-time
|
|
+@opindex --full-time
|
|
+Produce long format directory listings, and list times in full. It is
|
|
+equivalent to using @option{--format=long} with
|
|
+@option{--time-style=full-iso} (@pxref{Formatting file timestamps}).
|
|
+
|
|
+@item -g
|
|
+@opindex -g
|
|
+Produce long format directory listings, but don't display owner information.
|
|
+
|
|
+@item -G
|
|
+@itemx --no-group
|
|
+@opindex -G
|
|
+@opindex --no-group
|
|
+Inhibit display of group information in a long format directory listing.
|
|
+(This is the default in some non-@sc{gnu} versions of @command{ls}, so we
|
|
+provide this option for compatibility.)
|
|
+
|
|
+@optHumanReadable
|
|
+
|
|
+@item -i
|
|
+@itemx --inode
|
|
+@opindex -i
|
|
+@opindex --inode
|
|
+@cindex inode number, printing
|
|
+Print the inode number (also called the file serial number and index
|
|
+number) of each file to the left of the file name. (This number
|
|
+uniquely identifies each file within a particular file system.)
|
|
+
|
|
+@item -l
|
|
+@itemx --format=long
|
|
+@itemx --format=verbose
|
|
+@opindex -l
|
|
+@opindex --format
|
|
+@opindex long ls @r{format}
|
|
+@opindex verbose ls @r{format}
|
|
+In addition to the name of each file, print the file type, file mode bits,
|
|
+number of hard links, owner name, group name, size, and
|
|
+timestamp (@pxref{Formatting file timestamps}), normally
|
|
+the modification time. Print question marks for information that
|
|
+cannot be determined.
|
|
+
|
|
+Normally the size is printed as a byte count without punctuation, but
|
|
+this can be overridden (@pxref{Block size}). For example, @option{-h}
|
|
+prints an abbreviated, human-readable count, and
|
|
+@samp{--block-size="'1"} prints a byte count with the thousands
|
|
+separator of the current locale.
|
|
+
|
|
+For each directory that is listed, preface the files with a line
|
|
+@samp{total @var{blocks}}, where @var{blocks} is the total disk allocation
|
|
+for all files in that directory. The block size currently defaults to 1024
|
|
+bytes, but this can be overridden (@pxref{Block size}).
|
|
+The @var{blocks} computed counts each hard link separately;
|
|
+this is arguably a deficiency.
|
|
+
|
|
+The file type is one of the following characters:
|
|
+
|
|
+@c The commented-out entries are ones we're not sure about.
|
|
+
|
|
+@table @samp
|
|
+@item -
|
|
+regular file
|
|
+@item b
|
|
+block special file
|
|
+@item c
|
|
+character special file
|
|
+@item C
|
|
+high performance (``contiguous data'') file
|
|
+@item d
|
|
+directory
|
|
+@item D
|
|
+door (Solaris 2.5 and up)
|
|
+@c @item F
|
|
+@c semaphore, if this is a distinct file type
|
|
+@item l
|
|
+symbolic link
|
|
+@c @item m
|
|
+@c multiplexed file (7th edition Unix; obsolete)
|
|
+@item M
|
|
+off-line (``migrated'') file (Cray DMF)
|
|
+@item n
|
|
+network special file (HP-UX)
|
|
+@item p
|
|
+FIFO (named pipe)
|
|
+@item P
|
|
+port (Solaris 10 and up)
|
|
+@c @item Q
|
|
+@c message queue, if this is a distinct file type
|
|
+@item s
|
|
+socket
|
|
+@c @item S
|
|
+@c shared memory object, if this is a distinct file type
|
|
+@c @item T
|
|
+@c typed memory object, if this is a distinct file type
|
|
+@c @item w
|
|
+@c whiteout (4.4BSD; not implemented)
|
|
+@item ?
|
|
+some other file type
|
|
+@end table
|
|
+
|
|
+@cindex permissions, output by @command{ls}
|
|
+The file mode bits listed are similar to symbolic mode specifications
|
|
+(@pxref{Symbolic Modes}). But @command{ls} combines multiple bits into the
|
|
+third character of each set of permissions as follows:
|
|
+
|
|
+@table @samp
|
|
+@item s
|
|
+If the set-user-ID or set-group-ID bit and the corresponding executable bit
|
|
+are both set.
|
|
+
|
|
+@item S
|
|
+If the set-user-ID or set-group-ID bit is set but the corresponding
|
|
+executable bit is not set.
|
|
+
|
|
+@item t
|
|
+If the restricted deletion flag or sticky bit, and the
|
|
+other-executable bit, are both set. The restricted deletion flag is
|
|
+another name for the sticky bit. @xref{Mode Structure}.
|
|
+
|
|
+@item T
|
|
+If the restricted deletion flag or sticky bit is set but the
|
|
+other-executable bit is not set.
|
|
+
|
|
+@item x
|
|
+If the executable bit is set and none of the above apply.
|
|
+
|
|
+@item -
|
|
+Otherwise.
|
|
+@end table
|
|
+
|
|
+Following the file mode bits is a single character that specifies
|
|
+whether an alternate access method such as an access control list
|
|
+applies to the file. When the character following the file mode bits is a
|
|
+space, there is no alternate access method. When it is a printing
|
|
+character, then there is such a method.
|
|
+
|
|
+GNU @command{ls} uses a @samp{.} character to indicate a file
|
|
+with an SELinux security context, but no other alternate access method.
|
|
+
|
|
+A file with any other combination of alternate access methods
|
|
+is marked with a @samp{+} character.
|
|
+
|
|
+@item -n
|
|
+@itemx --numeric-uid-gid
|
|
+@opindex -n
|
|
+@opindex --numeric-uid-gid
|
|
+@cindex numeric uid and gid
|
|
+@cindex numeric user and group IDs
|
|
+Produce long format directory listings, but
|
|
+display numeric user and group IDs instead of the owner and group names.
|
|
+
|
|
+@item -o
|
|
+@opindex -o
|
|
+Produce long format directory listings, but don't display group information.
|
|
+It is equivalent to using @option{--format=long} with @option{--no-group} .
|
|
+
|
|
+@item -s
|
|
+@itemx --size
|
|
+@opindex -s
|
|
+@opindex --size
|
|
+@cindex disk allocation
|
|
+@cindex size of files, reporting
|
|
+Print the disk allocation of each file to the left of the file name.
|
|
+This is the amount of disk space used by the file, which is usually a
|
|
+bit more than the file's size, but it can be less if the file has holes.
|
|
+
|
|
+Normally the disk allocation is printed in units of
|
|
+1024 bytes, but this can be overridden (@pxref{Block size}).
|
|
+
|
|
+@cindex NFS mounts from BSD to HP-UX
|
|
+For files that are NFS-mounted from an HP-UX system to a BSD system,
|
|
+this option reports sizes that are half the correct values. On HP-UX
|
|
+systems, it reports sizes that are twice the correct values for files
|
|
+that are NFS-mounted from BSD systems. This is due to a flaw in HP-UX;
|
|
+it also affects the HP-UX @command{ls} program.
|
|
+
|
|
+@optSi
|
|
+
|
|
+@item -Z
|
|
+@itemx --context
|
|
+@opindex -Z
|
|
+@opindex --context
|
|
+@cindex SELinux
|
|
+@cindex security context
|
|
+Display the SELinux security context or @samp{?} if none is found.
|
|
+When used with the @option{-l} option, print the security context
|
|
+to the left of the size column.
|
|
+
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Sorting the output
|
|
+@subsection Sorting the output
|
|
+
|
|
+@cindex sorting @command{ls} output
|
|
+These options change the order in which @command{ls} sorts the information
|
|
+it outputs. By default, sorting is done by character code
|
|
+(e.g., @acronym{ASCII} order).
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -c
|
|
+@itemx --time=ctime
|
|
+@itemx --time=status
|
|
+@opindex -c
|
|
+@opindex --time
|
|
+@opindex ctime@r{, printing or sorting by}
|
|
+@opindex status time@r{, printing or sorting by}
|
|
+@opindex use time@r{, printing or sorting files by}
|
|
+If the long listing format (e.g., @option{-l}, @option{-o}) is being used,
|
|
+print the status change time (the @samp{ctime} in the inode) instead of
|
|
+the modification time.
|
|
+When explicitly sorting by time (@option{--sort=time} or @option{-t})
|
|
+or when not using a long listing format,
|
|
+sort according to the status change time.
|
|
+
|
|
+@item -f
|
|
+@opindex -f
|
|
+@cindex unsorted directory listing
|
|
+@cindex directory order, listing by
|
|
+Primarily, like @option{-U}---do not sort; list the files in whatever
|
|
+order they are stored in the directory. But also enable @option{-a} (list
|
|
+all files) and disable @option{-l}, @option{--color}, and @option{-s} (if they
|
|
+were specified before the @option{-f}).
|
|
+
|
|
+@item -r
|
|
+@itemx --reverse
|
|
+@opindex -r
|
|
+@opindex --reverse
|
|
+@cindex reverse sorting
|
|
+Reverse whatever the sorting method is---e.g., list files in reverse
|
|
+alphabetical order, youngest first, smallest first, or whatever.
|
|
+
|
|
+@item -S
|
|
+@itemx --sort=size
|
|
+@opindex -S
|
|
+@opindex --sort
|
|
+@opindex size of files@r{, sorting files by}
|
|
+Sort by file size, largest first.
|
|
+
|
|
+@item -t
|
|
+@itemx --sort=time
|
|
+@opindex -t
|
|
+@opindex --sort
|
|
+@opindex modification time@r{, sorting files by}
|
|
+Sort by modification time (the @samp{mtime} in the inode), newest first.
|
|
+
|
|
+@item -u
|
|
+@itemx --time=atime
|
|
+@itemx --time=access
|
|
+@itemx --time=use
|
|
+@opindex -u
|
|
+@opindex --time
|
|
+@opindex use time@r{, printing or sorting files by}
|
|
+@opindex atime@r{, printing or sorting files by}
|
|
+@opindex access time@r{, printing or sorting files by}
|
|
+If the long listing format (e.g., @option{--format=long}) is being used,
|
|
+print the last access time (the @samp{atime} in the inode).
|
|
+When explicitly sorting by time (@option{--sort=time} or @option{-t})
|
|
+or when not using a long listing format, sort according to the access time.
|
|
+
|
|
+@item -U
|
|
+@itemx --sort=none
|
|
+@opindex -U
|
|
+@opindex --sort
|
|
+@opindex none@r{, sorting option for @command{ls}}
|
|
+Do not sort; list the files in whatever order they are
|
|
+stored in the directory. (Do not do any of the other unrelated things
|
|
+that @option{-f} does.) This is especially useful when listing very large
|
|
+directories, since not doing any sorting can be noticeably faster.
|
|
+
|
|
+@item -v
|
|
+@itemx --sort=version
|
|
+@opindex -v
|
|
+@opindex --sort
|
|
+@opindex version@r{, sorting option for @command{ls}}
|
|
+Sort by version name and number, lowest first. It behaves like a default
|
|
+sort, except that each sequence of decimal digits is treated numerically
|
|
+as an index/version number. (@xref{Details about version sort}.)
|
|
+
|
|
+@item -X
|
|
+@itemx --sort=extension
|
|
+@opindex -X
|
|
+@opindex --sort
|
|
+@opindex extension@r{, sorting files by}
|
|
+Sort directory contents alphabetically by file extension (characters
|
|
+after the last @samp{.}); files with no extension are sorted first.
|
|
+
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Details about version sort
|
|
+@subsection Details about version sort
|
|
+
|
|
+The version sort takes into account the fact that file names frequently include
|
|
+indices or version numbers. Standard sorting functions usually do not produce
|
|
+the ordering that people expect because comparisons are made on a
|
|
+character-by-character basis. The version
|
|
+sort addresses this problem, and is especially useful when browsing
|
|
+directories that contain many files with indices/version numbers in their
|
|
+names:
|
|
+
|
|
+@example
|
|
+$ ls -1 $ ls -1v
|
|
+foo.zml-1.gz foo.zml-1.gz
|
|
+foo.zml-100.gz foo.zml-2.gz
|
|
+foo.zml-12.gz foo.zml-6.gz
|
|
+foo.zml-13.gz foo.zml-12.gz
|
|
+foo.zml-2.gz foo.zml-13.gz
|
|
+foo.zml-25.gz foo.zml-25.gz
|
|
+foo.zml-6.gz foo.zml-100.gz
|
|
+@end example
|
|
+
|
|
+Version-sorted strings are compared such that if @var{ver1} and @var{ver2}
|
|
+are version numbers and @var{prefix} and @var{suffix} (@var{suffix} matching
|
|
+the regular expression @samp{(\.[A-Za-z~][A-Za-z0-9~]*)*}) are strings then
|
|
+@var{ver1} < @var{ver2} implies that the name composed of
|
|
+``@var{prefix} @var{ver1} @var{suffix}'' sorts before
|
|
+``@var{prefix} @var{ver2} @var{suffix}''.
|
|
+
|
|
+Note also that leading zeros of numeric parts are ignored:
|
|
+
|
|
+@example
|
|
+$ ls -1 $ ls -1v
|
|
+abc-1.007.tgz abc-1.01a.tgz
|
|
+abc-1.012b.tgz abc-1.007.tgz
|
|
+abc-1.01a.tgz abc-1.012b.tgz
|
|
+@end example
|
|
+
|
|
+This functionality is implemented using gnulib's @code{filevercmp} function.
|
|
+One result of that implementation decision is that @samp{ls -v}
|
|
+and @samp{sort -V} do not use the locale category, @env{LC_COLLATE},
|
|
+which means non-numeric prefixes are sorted as if @env{LC_COLLATE} were set
|
|
+to @samp{C}.
|
|
+
|
|
+@node General output formatting
|
|
+@subsection General output formatting
|
|
+
|
|
+These options affect the appearance of the overall output.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -1
|
|
+@itemx --format=single-column
|
|
+@opindex -1
|
|
+@opindex --format
|
|
+@opindex single-column @r{output of files}
|
|
+List one file per line. This is the default for @command{ls} when standard
|
|
+output is not a terminal.
|
|
+
|
|
+@item -C
|
|
+@itemx --format=vertical
|
|
+@opindex -C
|
|
+@opindex --format
|
|
+@opindex vertical @r{sorted files in columns}
|
|
+List files in columns, sorted vertically. This is the default for
|
|
+@command{ls} if standard output is a terminal. It is always the default
|
|
+for the @command{dir} program.
|
|
+@sc{gnu} @command{ls} uses variable width columns to display as many files as
|
|
+possible in the fewest lines.
|
|
+
|
|
+@item --color [=@var{when}]
|
|
+@opindex --color
|
|
+@cindex color, distinguishing file types with
|
|
+Specify whether to use color for distinguishing file types. @var{when}
|
|
+may be omitted, or one of:
|
|
+@itemize @bullet
|
|
+@item none
|
|
+@vindex none @r{color option}
|
|
+- Do not use color at all. This is the default.
|
|
+@item auto
|
|
+@vindex auto @r{color option}
|
|
+@cindex terminal, using color iff
|
|
+- Only use color if standard output is a terminal.
|
|
+@item always
|
|
+@vindex always @r{color option}
|
|
+- Always use color.
|
|
+@end itemize
|
|
+Specifying @option{--color} and no @var{when} is equivalent to
|
|
+@option{--color=always}.
|
|
+Piping a colorized listing through a pager like @command{more} or
|
|
+@command{less} usually produces unreadable results. However, using
|
|
+@code{more -f} does seem to work.
|
|
+
|
|
+@item -F
|
|
+@itemx --classify
|
|
+@itemx --indicator-style=classify
|
|
+@opindex -F
|
|
+@opindex --classify
|
|
+@opindex --indicator-style
|
|
+@cindex file type and executables, marking
|
|
+@cindex executables and file type, marking
|
|
+Append a character to each file name indicating the file type. Also,
|
|
+for regular files that are executable, append @samp{*}. The file type
|
|
+indicators are @samp{/} for directories, @samp{@@} for symbolic links,
|
|
+@samp{|} for FIFOs, @samp{=} for sockets, @samp{>} for doors,
|
|
+and nothing for regular files.
|
|
+@c The following sentence is the same as the one for -d.
|
|
+Do not follow symbolic links listed on the
|
|
+command line unless the @option{--dereference-command-line} (@option{-H}),
|
|
+@option{--dereference} (@option{-L}), or
|
|
+@option{--dereference-command-line-symlink-to-dir} options are specified.
|
|
+
|
|
+@item --file-type
|
|
+@itemx --indicator-style=file-type
|
|
+@opindex --file-type
|
|
+@opindex --indicator-style
|
|
+@cindex file type, marking
|
|
+Append a character to each file name indicating the file type. This is
|
|
+like @option{-F}, except that executables are not marked.
|
|
+
|
|
+@item --indicator-style=@var{word}
|
|
+@opindex --indicator-style
|
|
+Append a character indicator with style @var{word} to entry names,
|
|
+as follows:
|
|
+
|
|
+@table @samp
|
|
+@item none
|
|
+Do not append any character indicator; this is the default.
|
|
+@item slash
|
|
+Append @samp{/} for directories. This is the same as the @option{-p}
|
|
+option.
|
|
+@item file-type
|
|
+Append @samp{/} for directories, @samp{@@} for symbolic links, @samp{|}
|
|
+for FIFOs, @samp{=} for sockets, and nothing for regular files. This is
|
|
+the same as the @option{--file-type} option.
|
|
+@item classify
|
|
+Append @samp{*} for executable regular files, otherwise behave as for
|
|
+@samp{file-type}. This is the same as the @option{-F} or
|
|
+@option{--classify} option.
|
|
+@end table
|
|
+
|
|
+@item -k
|
|
+@opindex -k
|
|
+Print file sizes in 1024-byte blocks, overriding the default block
|
|
+size (@pxref{Block size}).
|
|
+This option is equivalent to @option{--block-size=1K}.
|
|
+
|
|
+@item -m
|
|
+@itemx --format=commas
|
|
+@opindex -m
|
|
+@opindex --format
|
|
+@opindex commas@r{, outputting between files}
|
|
+List files horizontally, with as many as will fit on each line,
|
|
+separated by @samp{, } (a comma and a space).
|
|
+
|
|
+@item -p
|
|
+@itemx --indicator-style=slash
|
|
+@opindex -p
|
|
+@opindex --indicator-style
|
|
+@cindex file type, marking
|
|
+Append a @samp{/} to directory names.
|
|
+
|
|
+@item -x
|
|
+@itemx --format=across
|
|
+@itemx --format=horizontal
|
|
+@opindex -x
|
|
+@opindex --format
|
|
+@opindex across@r{, listing files}
|
|
+@opindex horizontal@r{, listing files}
|
|
+List the files in columns, sorted horizontally.
|
|
+
|
|
+@item -T @var{cols}
|
|
+@itemx --tabsize=@var{cols}
|
|
+@opindex -T
|
|
+@opindex --tabsize
|
|
+Assume that each tab stop is @var{cols} columns wide. The default is 8.
|
|
+@command{ls} uses tabs where possible in the output, for efficiency. If
|
|
+@var{cols} is zero, do not use tabs at all.
|
|
+
|
|
+@c FIXME: remove in 2009, if Apple Terminal has been fixed for long enough.
|
|
+Some terminal emulators (at least Apple Terminal 1.5 (133) from Mac OS X 10.4.8)
|
|
+do not properly align columns to the right of a TAB following a
|
|
+non-@acronym{ASCII} byte. If you use such a terminal emulator, use the
|
|
+@option{-T0} option or put @code{TABSIZE=0} in your environment to tell
|
|
+@command{ls} to align using spaces, not tabs.
|
|
+
|
|
+@item -w
|
|
+@itemx --width=@var{cols}
|
|
+@opindex -w
|
|
+@opindex --width
|
|
+@vindex COLUMNS
|
|
+Assume the screen is @var{cols} columns wide. The default is taken
|
|
+from the terminal settings if possible; otherwise the environment
|
|
+variable @env{COLUMNS} is used if it is set; otherwise the default
|
|
+is 80.
|
|
+
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Formatting file timestamps
|
|
+@subsection Formatting file timestamps
|
|
+
|
|
+By default, file timestamps are listed in abbreviated form. Most
|
|
+locales use a timestamp like @samp{2002-03-30 23:45}. However, the
|
|
+default @acronym{POSIX} locale uses a date like @samp{Mar 30@ @ 2002}
|
|
+for non-recent timestamps, and a date-without-year and time like
|
|
+@samp{Mar 30 23:45} for recent timestamps.
|
|
+
|
|
+A timestamp is considered to be @dfn{recent} if it is less than six
|
|
+months old, and is not dated in the future. If a timestamp dated
|
|
+today is not listed in recent form, the timestamp is in the future,
|
|
+which means you probably have clock skew problems which may break
|
|
+programs like @command{make} that rely on file timestamps.
|
|
+
|
|
+@vindex TZ
|
|
+Time stamps are listed according to the time zone rules specified by
|
|
+the @env{TZ} environment variable, or by the system default rules if
|
|
+@env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone
|
|
+with @env{TZ}, libc, The GNU C Library Reference Manual}.
|
|
+
|
|
+The following option changes how file timestamps are printed.
|
|
+
|
|
+@table @samp
|
|
+@item --time-style=@var{style}
|
|
+@opindex --time-style
|
|
+@cindex time style
|
|
+List timestamps in style @var{style}. The @var{style} should
|
|
+be one of the following:
|
|
+
|
|
+@table @samp
|
|
+@item +@var{format}
|
|
+@vindex LC_TIME
|
|
+List timestamps using @var{format}, where @var{format} is interpreted
|
|
+like the format argument of @command{date} (@pxref{date invocation}).
|
|
+For example, @option{--time-style="+%Y-%m-%d %H:%M:%S"} causes
|
|
+@command{ls} to list timestamps like @samp{2002-03-30 23:45:56}. As
|
|
+with @command{date}, @var{format}'s interpretation is affected by the
|
|
+@env{LC_TIME} locale category.
|
|
+
|
|
+If @var{format} contains two format strings separated by a newline,
|
|
+the former is used for non-recent files and the latter for recent
|
|
+files; if you want output columns to line up, you may need to insert
|
|
+spaces in one of the two formats.
|
|
+
|
|
+@item full-iso
|
|
+List timestamps in full using @acronym{ISO} 8601 date, time, and time zone
|
|
+format with nanosecond precision, e.g., @samp{2002-03-30
|
|
+23:45:56.477817180 -0700}. This style is equivalent to
|
|
+@samp{+%Y-%m-%d %H:%M:%S.%N %z}.
|
|
+
|
|
+This is useful because the time output includes all the information that
|
|
+is available from the operating system. For example, this can help
|
|
+explain @command{make}'s behavior, since @acronym{GNU} @command{make}
|
|
+uses the full timestamp to determine whether a file is out of date.
|
|
+
|
|
+@item long-iso
|
|
+List @acronym{ISO} 8601 date and time in minutes, e.g.,
|
|
+@samp{2002-03-30 23:45}. These timestamps are shorter than
|
|
+@samp{full-iso} timestamps, and are usually good enough for everyday
|
|
+work. This style is equivalent to @samp{+%Y-%m-%d %H:%M}.
|
|
+
|
|
+@item iso
|
|
+List @acronym{ISO} 8601 dates for non-recent timestamps (e.g.,
|
|
+@samp{2002-03-30@ }), and @acronym{ISO} 8601 month, day, hour, and
|
|
+minute for recent timestamps (e.g., @samp{03-30 23:45}). These
|
|
+timestamps are uglier than @samp{long-iso} timestamps, but they carry
|
|
+nearly the same information in a smaller space and their brevity helps
|
|
+@command{ls} output fit within traditional 80-column output lines.
|
|
+The following two @command{ls} invocations are equivalent:
|
|
+
|
|
+@example
|
|
+newline='
|
|
+'
|
|
+ls -l --time-style="+%Y-%m-%d $newline%m-%d %H:%M"
|
|
+ls -l --time-style="iso"
|
|
+@end example
|
|
+
|
|
+@item locale
|
|
+@vindex LC_TIME
|
|
+List timestamps in a locale-dependent form. For example, a Finnish
|
|
+locale might list non-recent timestamps like @samp{maalis 30@ @ 2002}
|
|
+and recent timestamps like @samp{maalis 30 23:45}. Locale-dependent
|
|
+timestamps typically consume more space than @samp{iso} timestamps and
|
|
+are harder for programs to parse because locale conventions vary so
|
|
+widely, but they are easier for many people to read.
|
|
+
|
|
+The @env{LC_TIME} locale category specifies the timestamp format. The
|
|
+default @acronym{POSIX} locale uses timestamps like @samp{Mar 30@
|
|
+@ 2002} and @samp{Mar 30 23:45}; in this locale, the following two
|
|
+@command{ls} invocations are equivalent:
|
|
+
|
|
+@example
|
|
+newline='
|
|
+'
|
|
+ls -l --time-style="+%b %e %Y$newline%b %e %H:%M"
|
|
+ls -l --time-style="locale"
|
|
+@end example
|
|
+
|
|
+Other locales behave differently. For example, in a German locale,
|
|
+@option{--time-style="locale"} might be equivalent to
|
|
+@option{--time-style="+%e. %b %Y $newline%e. %b %H:%M"}
|
|
+and might generate timestamps like @samp{30. M@"ar 2002@ } and
|
|
+@samp{30. M@"ar 23:45}.
|
|
+
|
|
+@item posix-@var{style}
|
|
+@vindex LC_TIME
|
|
+List @acronym{POSIX}-locale timestamps if the @env{LC_TIME} locale
|
|
+category is @acronym{POSIX}, @var{style} timestamps otherwise. For
|
|
+example, the @samp{posix-long-iso} style lists
|
|
+timestamps like @samp{Mar 30@ @ 2002} and @samp{Mar 30 23:45} when in
|
|
+the @acronym{POSIX} locale, and like @samp{2002-03-30 23:45} otherwise.
|
|
+@end table
|
|
+@end table
|
|
+
|
|
+@vindex TIME_STYLE
|
|
+You can specify the default value of the @option{--time-style} option
|
|
+with the environment variable @env{TIME_STYLE}; if @env{TIME_STYLE} is not set
|
|
+the default style is @samp{locale}. @acronym{GNU} Emacs 21.3 and
|
|
+later use the @option{--dired} option and therefore can parse any date
|
|
+format, but if you are using Emacs 21.1 or 21.2 and specify a
|
|
+non-@acronym{POSIX} locale you may need to set
|
|
+@samp{TIME_STYLE="posix-long-iso"}.
|
|
+
|
|
+To avoid certain denial-of-service attacks, timestamps that would be
|
|
+longer than 1000 bytes may be treated as errors.
|
|
+
|
|
+
|
|
+@node Formatting the file names
|
|
+@subsection Formatting the file names
|
|
+
|
|
+These options change how file names themselves are printed.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -b
|
|
+@itemx --escape
|
|
+@itemx --quoting-style=escape
|
|
+@opindex -b
|
|
+@opindex --escape
|
|
+@opindex --quoting-style
|
|
+@cindex backslash sequences for file names
|
|
+Quote nongraphic characters in file names using alphabetic and octal
|
|
+backslash sequences like those used in C.
|
|
+
|
|
+@item -N
|
|
+@itemx --literal
|
|
+@itemx --quoting-style=literal
|
|
+@opindex -N
|
|
+@opindex --literal
|
|
+@opindex --quoting-style
|
|
+Do not quote file names. However, with @command{ls} nongraphic
|
|
+characters are still printed as question marks if the output is a
|
|
+terminal and you do not specify the @option{--show-control-chars}
|
|
+option.
|
|
+
|
|
+@item -q
|
|
+@itemx --hide-control-chars
|
|
+@opindex -q
|
|
+@opindex --hide-control-chars
|
|
+Print question marks instead of nongraphic characters in file names.
|
|
+This is the default if the output is a terminal and the program is
|
|
+@command{ls}.
|
|
+
|
|
+@item -Q
|
|
+@itemx --quote-name
|
|
+@itemx --quoting-style=c
|
|
+@opindex -Q
|
|
+@opindex --quote-name
|
|
+@opindex --quoting-style
|
|
+Enclose file names in double quotes and quote nongraphic characters as
|
|
+in C.
|
|
+
|
|
+@item --quoting-style=@var{word}
|
|
+@opindex --quoting-style
|
|
+@cindex quoting style
|
|
+Use style @var{word} to quote file names and other strings that may
|
|
+contain arbitrary characters. The @var{word} should
|
|
+be one of the following:
|
|
+
|
|
+@table @samp
|
|
+@item literal
|
|
+Output strings as-is; this is the same as the @option{-N} or
|
|
+@option{--literal} option.
|
|
+@item shell
|
|
+Quote strings for the shell if they contain shell metacharacters or would
|
|
+cause ambiguous output.
|
|
+The quoting is suitable for @acronym{POSIX}-compatible shells like
|
|
+@command{bash}, but it does not always work for incompatible shells
|
|
+like @command{csh}.
|
|
+@item shell-always
|
|
+Quote strings for the shell, even if they would normally not require quoting.
|
|
+@item c
|
|
+Quote strings as for C character string literals, including the
|
|
+surrounding double-quote characters; this is the same as the
|
|
+@option{-Q} or @option{--quote-name} option.
|
|
+@item escape
|
|
+Quote strings as for C character string literals, except omit the
|
|
+surrounding double-quote
|
|
+characters; this is the same as the @option{-b} or @option{--escape} option.
|
|
+@item clocale
|
|
+Quote strings as for C character string literals, except use
|
|
+surrounding quotation marks appropriate for the
|
|
+locale.
|
|
+@item locale
|
|
+@c Use @t instead of @samp to avoid duplicate quoting in some output styles.
|
|
+Quote strings as for C character string literals, except use
|
|
+surrounding quotation marks appropriate for the locale, and quote
|
|
+@t{`like this'} instead of @t{"like
|
|
+this"} in the default C locale. This looks nicer on many displays.
|
|
+@end table
|
|
+
|
|
+You can specify the default value of the @option{--quoting-style} option
|
|
+with the environment variable @env{QUOTING_STYLE}. If that environment
|
|
+variable is not set, the default value is @samp{literal}, but this
|
|
+default may change to @samp{shell} in a future version of this package.
|
|
+
|
|
+@item --show-control-chars
|
|
+@opindex --show-control-chars
|
|
+Print nongraphic characters as-is in file names.
|
|
+This is the default unless the output is a terminal and the program is
|
|
+@command{ls}.
|
|
+
|
|
+@end table
|
|
+
|
|
+
|
|
+@node dir invocation
|
|
+@section @command{dir}: Briefly list directory contents
|
|
+
|
|
+@pindex dir
|
|
+@cindex directory listing, brief
|
|
+
|
|
+@command{dir} is equivalent to @code{ls -C
|
|
+-b}; that is, by default files are listed in columns, sorted vertically,
|
|
+and special characters are represented by backslash escape sequences.
|
|
+
|
|
+@xref{ls invocation, @command{ls}}.
|
|
+
|
|
+
|
|
+@node vdir invocation
|
|
+@section @command{vdir}: Verbosely list directory contents
|
|
+
|
|
+@pindex vdir
|
|
+@cindex directory listing, verbose
|
|
+
|
|
+@command{vdir} is equivalent to @code{ls -l
|
|
+-b}; that is, by default files are listed in long format and special
|
|
+characters are represented by backslash escape sequences.
|
|
+
|
|
+@node dircolors invocation
|
|
+@section @command{dircolors}: Color setup for @command{ls}
|
|
+
|
|
+@pindex dircolors
|
|
+@cindex color setup
|
|
+@cindex setup for color
|
|
+
|
|
+@command{dircolors} outputs a sequence of shell commands to set up the
|
|
+terminal for color output from @command{ls} (and @command{dir}, etc.).
|
|
+Typical usage:
|
|
+
|
|
+@example
|
|
+eval "`dircolors [@var{option}]@dots{} [@var{file}]`"
|
|
+@end example
|
|
+
|
|
+If @var{file} is specified, @command{dircolors} reads it to determine which
|
|
+colors to use for which file types and extensions. Otherwise, a
|
|
+precompiled database is used. For details on the format of these files,
|
|
+run @samp{dircolors --print-database}.
|
|
+
|
|
+To make @command{dircolors} read a @file{~/.dircolors} file if it
|
|
+exists, you can put the following lines in your @file{~/.bashrc} (or
|
|
+adapt them to your favorite shell):
|
|
+
|
|
+@example
|
|
+d=.dircolors
|
|
+test -r $d && eval "$(dircolors $d)"
|
|
+@end example
|
|
+
|
|
+@vindex LS_COLORS
|
|
+@vindex SHELL @r{environment variable, and color}
|
|
+The output is a shell command to set the @env{LS_COLORS} environment
|
|
+variable. You can specify the shell syntax to use on the command line,
|
|
+or @command{dircolors} will guess it from the value of the @env{SHELL}
|
|
+environment variable.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+@item -b
|
|
+@itemx --sh
|
|
+@itemx --bourne-shell
|
|
+@opindex -b
|
|
+@opindex --sh
|
|
+@opindex --bourne-shell
|
|
+@cindex Bourne shell syntax for color setup
|
|
+@cindex @command{sh} syntax for color setup
|
|
+Output Bourne shell commands. This is the default if the @env{SHELL}
|
|
+environment variable is set and does not end with @samp{csh} or
|
|
+@samp{tcsh}.
|
|
+
|
|
+@item -c
|
|
+@itemx --csh
|
|
+@itemx --c-shell
|
|
+@opindex -c
|
|
+@opindex --csh
|
|
+@opindex --c-shell
|
|
+@cindex C shell syntax for color setup
|
|
+@cindex @command{csh} syntax for color setup
|
|
+Output C shell commands. This is the default if @code{SHELL} ends with
|
|
+@command{csh} or @command{tcsh}.
|
|
+
|
|
+@item -p
|
|
+@itemx --print-database
|
|
+@opindex -p
|
|
+@opindex --print-database
|
|
+@cindex color database, printing
|
|
+@cindex database for color setup, printing
|
|
+@cindex printing color database
|
|
+Print the (compiled-in) default color configuration database. This
|
|
+output is itself a valid configuration file, and is fairly descriptive
|
|
+of the possibilities.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node Basic operations
|
|
+@chapter Basic operations
|
|
+
|
|
+@cindex manipulating files
|
|
+
|
|
+This chapter describes the commands for basic file manipulation:
|
|
+copying, moving (renaming), and deleting (removing).
|
|
+
|
|
+@menu
|
|
+* cp invocation:: Copy files.
|
|
+* 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.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node cp invocation
|
|
+@section @command{cp}: Copy files and directories
|
|
+
|
|
+@pindex cp
|
|
+@cindex copying files and directories
|
|
+@cindex files, copying
|
|
+@cindex directories, copying
|
|
+
|
|
+@command{cp} copies files (or, optionally, directories). The copy is
|
|
+completely independent of the original. You can either copy one file to
|
|
+another, or copy arbitrarily many files to a destination directory.
|
|
+Synopses:
|
|
+
|
|
+@example
|
|
+cp [@var{option}]@dots{} [-T] @var{source} @var{dest}
|
|
+cp [@var{option}]@dots{} @var{source}@dots{} @var{directory}
|
|
+cp [@var{option}]@dots{} -t @var{directory} @var{source}@dots{}
|
|
+@end example
|
|
+
|
|
+@itemize @bullet
|
|
+@item
|
|
+If two file names are given, @command{cp} copies the first file to the
|
|
+second.
|
|
+
|
|
+@item
|
|
+If the @option{--target-directory} (@option{-t}) option is given, or
|
|
+failing that if the last file is a directory and the
|
|
+@option{--no-target-directory} (@option{-T}) option is not given,
|
|
+@command{cp} copies each @var{source} file to the specified directory,
|
|
+using the @var{source}s' names.
|
|
+@end itemize
|
|
+
|
|
+Generally, files are written just as they are read. For exceptions,
|
|
+see the @option{--sparse} option below.
|
|
+
|
|
+By default, @command{cp} does not copy directories. However, the
|
|
+@option{-R}, @option{-a}, and @option{-r} options cause @command{cp} to
|
|
+copy recursively by descending into source directories and copying files
|
|
+to corresponding destination directories.
|
|
+
|
|
+When copying from a symbolic link, @command{cp} normally follows the
|
|
+link only when not copying
|
|
+recursively. This default can be overridden with the
|
|
+@option{--archive} (@option{-a}), @option{-d}, @option{--dereference}
|
|
+(@option{-L}), @option{--no-dereference} (@option{-P}), and
|
|
+@option{-H} options. If more than one of these options is specified,
|
|
+the last one silently overrides the others.
|
|
+
|
|
+When copying to a symbolic link, @command{cp} follows the
|
|
+link only when it refers to an existing regular file.
|
|
+However, when copying to a dangling symbolic link, @command{cp}
|
|
+refuses by default, and fails with a diagnostic, since the operation
|
|
+is inherently dangerous. This behavior is contrary to historical
|
|
+practice and to @acronym{POSIX}.
|
|
+Set @env{POSIXLY_CORRECT} to make @command{cp} attempt to create
|
|
+the target of a dangling destination symlink, in spite of the possible risk.
|
|
+Also, when an option like
|
|
+@option{--backup} or @option{--link} acts to rename or remove the
|
|
+destination before copying, @command{cp} renames or removes the
|
|
+symbolic link rather than the file it points to.
|
|
+
|
|
+By default, @command{cp} copies the contents of special files only
|
|
+when not copying recursively. This default can be overridden with the
|
|
+@option{--copy-contents} option.
|
|
+
|
|
+@cindex self-backups
|
|
+@cindex backups, making only
|
|
+@command{cp} generally refuses to copy a file onto itself, with the
|
|
+following exception: if @option{--force --backup} is specified with
|
|
+@var{source} and @var{dest} identical, and referring to a regular file,
|
|
+@command{cp} will make a backup file, either regular or numbered, as
|
|
+specified in the usual ways (@pxref{Backup options}). This is useful when
|
|
+you simply want to make a backup of an existing file before changing it.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+@item -a
|
|
+@itemx --archive
|
|
+@opindex -a
|
|
+@opindex --archive
|
|
+Preserve as much as possible of the structure and attributes of the
|
|
+original files in the copy (but do not attempt to preserve internal
|
|
+directory structure; i.e., @samp{ls -U} may list the entries in a copied
|
|
+directory in a different order).
|
|
+Try to preserve SELinux security context and extended attributes (xattr),
|
|
+but ignore any failure to do that and print no corresponding diagnostic.
|
|
+Equivalent to @option{-dR --preserve=all} with the reduced diagnostics.
|
|
+
|
|
+@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.
|
|
+As a special case, @command{cp} makes a backup of @var{source} when the force
|
|
+and backup options are given and @var{source} and @var{dest} are the same
|
|
+name for an existing, regular file. One useful application of this
|
|
+combination of options is this tiny Bourne shell script:
|
|
+
|
|
+@example
|
|
+#!/bin/sh
|
|
+# Usage: backup FILE...
|
|
+# Create a @sc{gnu}-style backup of each listed FILE.
|
|
+for i; do
|
|
+ cp --backup --force -- "$i" "$i"
|
|
+done
|
|
+@end example
|
|
+
|
|
+@item --copy-contents
|
|
+@cindex directories, copying recursively
|
|
+@cindex copying directories recursively
|
|
+@cindex recursively copying directories
|
|
+@cindex non-directories, copying as special files
|
|
+If copying recursively, copy the contents of any special files (e.g.,
|
|
+FIFOs and device files) as if they were regular files. This means
|
|
+trying to read the data in each source file and writing it to the
|
|
+destination. It is usually a mistake to use this option, as it
|
|
+normally has undesirable effects on special files like FIFOs and the
|
|
+ones typically found in the @file{/dev} directory. In most cases,
|
|
+@code{cp -R --copy-contents} will hang indefinitely trying to read
|
|
+from FIFOs and special files like @file{/dev/console}, and it will
|
|
+fill up your destination disk if you use it to copy @file{/dev/zero}.
|
|
+This option has no effect unless copying recursively, and it does not
|
|
+affect the copying of symbolic links.
|
|
+
|
|
+@item -d
|
|
+@opindex -d
|
|
+@cindex symbolic links, copying
|
|
+@cindex hard links, preserving
|
|
+Copy symbolic links as symbolic links rather than copying the files that
|
|
+they point to, and preserve hard links between source files in the copies.
|
|
+Equivalent to @option{--no-dereference --preserve=links}.
|
|
+
|
|
+@item -f
|
|
+@itemx --force
|
|
+@opindex -f
|
|
+@opindex --force
|
|
+When copying without this option and an existing destination file cannot
|
|
+be opened for writing, the copy fails. However, with @option{--force}),
|
|
+when a destination file cannot be opened, @command{cp} then removes it and
|
|
+tries to open it again. Contrast this behavior with that enabled by
|
|
+@option{--link} and @option{--symbolic-link}, whereby the destination file
|
|
+is never opened but rather is removed unconditionally. Also see the
|
|
+description of @option{--remove-destination}.
|
|
+
|
|
+This option is independent of the @option{--interactive} or
|
|
+@option{-i} option: neither cancels the effect of the other.
|
|
+
|
|
+This option is redundant if the @option{--no-clobber} or @option{-n} option is
|
|
+used.
|
|
+
|
|
+@item -H
|
|
+@opindex -H
|
|
+If a command line argument specifies a symbolic link, then copy the
|
|
+file it points to rather than the symbolic link itself. However,
|
|
+copy (preserving its nature) any symbolic link that is encountered
|
|
+via recursive traversal.
|
|
+
|
|
+@item -i
|
|
+@itemx --interactive
|
|
+@opindex -i
|
|
+@opindex --interactive
|
|
+When copying a file other than a directory, prompt whether to
|
|
+overwrite an existing destination file. The @option{-i} option overrides
|
|
+a previous @option{-n} option.
|
|
+
|
|
+@item -l
|
|
+@itemx --link
|
|
+@opindex -l
|
|
+@opindex --link
|
|
+Make hard links instead of copies of non-directories.
|
|
+
|
|
+@item -L
|
|
+@itemx --dereference
|
|
+@opindex -L
|
|
+@opindex --dereference
|
|
+Follow symbolic links when copying from them.
|
|
+With this option, @command{cp} cannot create a symbolic link.
|
|
+For example, a symlink (to regular file) in the source tree will be copied to
|
|
+a regular file in the destination tree.
|
|
+
|
|
+@item -n
|
|
+@itemx --no-clobber
|
|
+@opindex -n
|
|
+@opindex --no-clobber
|
|
+Do not overwrite an existing file. The @option{-n} option overrides a previous
|
|
+@option{-i} option. This option is mutually exclusive with @option{-b} or
|
|
+@option{--backup} option.
|
|
+
|
|
+@item -P
|
|
+@itemx --no-dereference
|
|
+@opindex -P
|
|
+@opindex --no-dereference
|
|
+@cindex symbolic links, copying
|
|
+Copy symbolic links as symbolic links rather than copying the files that
|
|
+they point to. This option affects only symbolic links in the source;
|
|
+symbolic links in the destination are always followed if possible.
|
|
+
|
|
+@item -p
|
|
+@itemx @w{@kbd{--preserve}[=@var{attribute_list}]}
|
|
+@opindex -p
|
|
+@opindex --preserve
|
|
+@cindex file information, preserving, extended attributes, xattr
|
|
+Preserve the specified attributes of the original files.
|
|
+If specified, the @var{attribute_list} must be a comma-separated list
|
|
+of one or more of the following strings:
|
|
+
|
|
+@table @samp
|
|
+@itemx mode
|
|
+Preserve the file mode bits and access control lists.
|
|
+@itemx ownership
|
|
+Preserve the owner and group. On most modern systems,
|
|
+only users with appropriate privileges may change the owner of a file,
|
|
+and ordinary users
|
|
+may preserve the group ownership of a file only if they happen to be
|
|
+a member of the desired group.
|
|
+@itemx timestamps
|
|
+Preserve the times of last access and last modification, when possible.
|
|
+On older systems, it is not possible to preserve these attributes
|
|
+when the affected file is a symbolic link.
|
|
+However, many systems now provide the @code{utimensat} function,
|
|
+which makes it possible even for symbolic links.
|
|
+@itemx links
|
|
+Preserve in the destination files
|
|
+any links between corresponding source files.
|
|
+Note that with @option{-L} or @option{-H}, this option can convert
|
|
+symbolic links to hard links. For example,
|
|
+@example
|
|
+$ mkdir c; : > a; ln -s a b; cp -aH a b c; ls -i1 c
|
|
+74161745 a
|
|
+74161745 b
|
|
+@end example
|
|
+@noindent
|
|
+Note the inputs: @file{b} is a symlink to regular file @file{a},
|
|
+yet the files in destination directory, @file{c/}, are hard-linked.
|
|
+Since @option{-a} implies @option{--preserve=links}, and since @option{-H}
|
|
+tells @command{cp} to dereference command line arguments, it sees two files
|
|
+with the same inode number, and preserves the perceived hard link.
|
|
+
|
|
+Here is a similar example that exercises @command{cp}'s @option{-L} option:
|
|
+@smallexample
|
|
+$ mkdir b c; (cd b; : > a; ln -s a b); cp -aL b c; ls -i1 c/b
|
|
+74163295 a
|
|
+74163295 b
|
|
+@end smallexample
|
|
+
|
|
+@itemx context
|
|
+Preserve SELinux security context of the file. @command{cp} will fail
|
|
+if the preserving of SELinux security context is not succesful.
|
|
+@itemx xattr
|
|
+Preserve extended attributes if @command{cp} is built with xattr support,
|
|
+and xattrs are supported and enabled on your file system.
|
|
+If SELinux context and/or ACLs are implemented using xattrs,
|
|
+they are preserved by this option as well.
|
|
+@itemx all
|
|
+Preserve all file attributes.
|
|
+Equivalent to specifying all of the above, but with the difference
|
|
+that failure to preserve SELinux security context or extended attributes
|
|
+does not change @command{cp}'s exit status.
|
|
+@command{cp} does diagnose such failures.
|
|
+@end table
|
|
+
|
|
+Using @option{--preserve} with no @var{attribute_list} is equivalent
|
|
+to @option{--preserve=mode,ownership,timestamps}.
|
|
+
|
|
+In the absence of this option, each destination file is created with the
|
|
+mode bits of the corresponding source file, minus the bits set in the
|
|
+umask and minus the set-user-ID and set-group-ID bits.
|
|
+@xref{File permissions}.
|
|
+
|
|
+@itemx @w{@kbd{--no-preserve}=@var{attribute_list}}
|
|
+@cindex file information, preserving
|
|
+Do not preserve the specified attributes. The @var{attribute_list}
|
|
+has the same form as for @option{--preserve}.
|
|
+
|
|
+@itemx --parents
|
|
+@opindex --parents
|
|
+@cindex parent directories and @command{cp}
|
|
+Form the name of each destination file by appending to the target
|
|
+directory a slash and the specified name of the source file. The last
|
|
+argument given to @command{cp} must be the name of an existing directory.
|
|
+For example, the command:
|
|
+
|
|
+@example
|
|
+cp --parents a/b/c existing_dir
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+copies the file @file{a/b/c} to @file{existing_dir/a/b/c}, creating
|
|
+any missing intermediate directories.
|
|
+
|
|
+@item -R
|
|
+@itemx -r
|
|
+@itemx --recursive
|
|
+@opindex -R
|
|
+@opindex -r
|
|
+@opindex --recursive
|
|
+@cindex directories, copying recursively
|
|
+@cindex copying directories recursively
|
|
+@cindex recursively copying directories
|
|
+@cindex non-directories, copying as special files
|
|
+Copy directories recursively. By default, do not follow symbolic
|
|
+links in the source; see the @option{--archive} (@option{-a}), @option{-d},
|
|
+@option{--dereference} (@option{-L}), @option{--no-dereference}
|
|
+(@option{-P}), and @option{-H} options. Special files are copied by
|
|
+creating a destination file of the same type as the source; see the
|
|
+@option{--copy-contents} option. It is not portable to use
|
|
+@option{-r} to copy symbolic links or special files. On some
|
|
+non-@sc{gnu} systems, @option{-r} implies the equivalent of
|
|
+@option{-L} and @option{--copy-contents} for historical reasons.
|
|
+Also, it is not portable to use @option{-R} to copy symbolic links
|
|
+unless you also specify @option{-P}, as @acronym{POSIX} allows
|
|
+implementations that dereference symbolic links by default.
|
|
+
|
|
+@item --reflink[=@var{when}]
|
|
+@opindex --reflink[=@var{when}]
|
|
+@cindex COW
|
|
+@cindex clone
|
|
+@cindex copy on write
|
|
+Perform a lightweight, copy-on-write (COW) copy.
|
|
+Copying with this option can succeed only on some file systems.
|
|
+Once it has succeeded, beware that the source and destination files
|
|
+share the same disk data blocks as long as they remain unmodified.
|
|
+Thus, if a disk I/O error affects data blocks of one of the files,
|
|
+the other suffers the exact same fate.
|
|
+
|
|
+The @var{when} value can be one of the following:
|
|
+
|
|
+@table @samp
|
|
+@item always
|
|
+The default behavior: if the copy-on-write operation is not supported
|
|
+then report the failure for each file and exit with a failure status.
|
|
+
|
|
+@item auto
|
|
+If the copy-on-write operation is not supported then fall back
|
|
+to the standard copy behaviour.
|
|
+@end table
|
|
+
|
|
+
|
|
+@item --remove-destination
|
|
+@opindex --remove-destination
|
|
+Remove each existing destination file before attempting to open it
|
|
+(contrast with @option{-f} above).
|
|
+
|
|
+@item --sparse=@var{when}
|
|
+@opindex --sparse=@var{when}
|
|
+@cindex sparse files, copying
|
|
+@cindex holes, copying files with
|
|
+@findex read @r{system call, and holes}
|
|
+A @dfn{sparse file} contains @dfn{holes}---a sequence of zero bytes that
|
|
+does not occupy any physical disk blocks; the @samp{read} system call
|
|
+reads these as zeros. This can both save considerable disk space and
|
|
+increase speed, since many binary files contain lots of consecutive zero
|
|
+bytes. By default, @command{cp} detects holes in input source files via a crude
|
|
+heuristic and makes the corresponding output file sparse as well.
|
|
+Only regular files may be sparse.
|
|
+
|
|
+The @var{when} value can be one of the following:
|
|
+
|
|
+@table @samp
|
|
+@item auto
|
|
+The default behavior: if the input file is sparse, attempt to make
|
|
+the output file sparse, too. However, if an output file exists but
|
|
+refers to a non-regular file, then do not attempt to make it sparse.
|
|
+
|
|
+@item always
|
|
+For each sufficiently long sequence of zero bytes in the input file,
|
|
+attempt to create a corresponding hole in the output file, even if the
|
|
+input file does not appear to be sparse.
|
|
+This is useful when the input file resides on a file system
|
|
+that does not support sparse files
|
|
+(for example, @samp{efs} file systems in SGI IRIX 5.3 and earlier),
|
|
+but the output file is on a type of file system that does support them.
|
|
+Holes may be created only in regular files, so if the destination file
|
|
+is of some other type, @command{cp} does not even try to make it sparse.
|
|
+
|
|
+@item never
|
|
+Never make the output file sparse.
|
|
+This is useful in creating a file for use with the @command{mkswap} command,
|
|
+since such a file must not have any holes.
|
|
+@end table
|
|
+
|
|
+@optStripTrailingSlashes
|
|
+
|
|
+@item -s
|
|
+@itemx --symbolic-link
|
|
+@opindex -s
|
|
+@opindex --symbolic-link
|
|
+@cindex symbolic links, copying with
|
|
+Make symbolic links instead of copies of non-directories. All source
|
|
+file names must be absolute (starting with @samp{/}) unless the
|
|
+destination files are in the current directory. This option merely
|
|
+results in an error message on systems that do not support symbolic links.
|
|
+
|
|
+@optBackupSuffix
|
|
+
|
|
+@optTargetDirectory
|
|
+
|
|
+@optNoTargetDirectory
|
|
+
|
|
+@item -u
|
|
+@itemx --update
|
|
+@opindex -u
|
|
+@opindex --update
|
|
+@cindex newer files, copying only
|
|
+Do not copy a non-directory that has an existing destination with the
|
|
+same or newer modification time. If time stamps are being preserved,
|
|
+the comparison is to the source time stamp truncated to the
|
|
+resolutions of the destination file system and of the system calls
|
|
+used to update time stamps; this avoids duplicate work if several
|
|
+@samp{cp -pu} commands are executed with the same source and
|
|
+destination.
|
|
+
|
|
+@item -v
|
|
+@itemx --verbose
|
|
+@opindex -v
|
|
+@opindex --verbose
|
|
+Print the name of each file before copying it.
|
|
+
|
|
+@item -x
|
|
+@itemx --one-file-system
|
|
+@opindex -x
|
|
+@opindex --one-file-system
|
|
+@cindex file systems, omitting copying to different
|
|
+Skip subdirectories that are on different file systems from the one that
|
|
+the copy started on.
|
|
+However, mount point directories @emph{are} copied.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node dd invocation
|
|
+@section @command{dd}: Convert and copy a file
|
|
+
|
|
+@pindex dd
|
|
+@cindex converting while copying a file
|
|
+
|
|
+@command{dd} copies a file (from standard input to standard output, by
|
|
+default) with a changeable I/O block size, while optionally performing
|
|
+conversions on it. Synopses:
|
|
+
|
|
+@example
|
|
+dd [@var{operand}]@dots{}
|
|
+dd @var{option}
|
|
+@end example
|
|
+
|
|
+The only options are @option{--help} and @option{--version}.
|
|
+@xref{Common options}. @command{dd} accepts the following operands.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item if=@var{file}
|
|
+@opindex if
|
|
+Read from @var{file} instead of standard input.
|
|
+
|
|
+@item of=@var{file}
|
|
+@opindex of
|
|
+Write to @var{file} instead of standard output. Unless
|
|
+@samp{conv=notrunc} is given, @command{dd} truncates @var{file} to zero
|
|
+bytes (or the size specified with @samp{seek=}).
|
|
+
|
|
+@item ibs=@var{bytes}
|
|
+@opindex ibs
|
|
+@cindex block size of input
|
|
+@cindex input block size
|
|
+Set the input block size to @var{bytes}.
|
|
+This makes @command{dd} read @var{bytes} per block.
|
|
+The default is 512 bytes.
|
|
+
|
|
+@item obs=@var{bytes}
|
|
+@opindex obs
|
|
+@cindex block size of output
|
|
+@cindex output block size
|
|
+Set the output block size to @var{bytes}.
|
|
+This makes @command{dd} write @var{bytes} per block.
|
|
+The default is 512 bytes.
|
|
+
|
|
+@item bs=@var{bytes}
|
|
+@opindex bs
|
|
+@cindex block size
|
|
+Set both input and output block sizes to @var{bytes}.
|
|
+This makes @command{dd} read and write @var{bytes} per block,
|
|
+overriding any @samp{ibs} and @samp{obs} settings.
|
|
+In addition, if no data-transforming @option{conv} option is specified,
|
|
+each input block is copied to the output as a single block,
|
|
+without aggregating short reads.
|
|
+
|
|
+@item cbs=@var{bytes}
|
|
+@opindex cbs
|
|
+@cindex block size of conversion
|
|
+@cindex conversion block size
|
|
+@cindex fixed-length records, converting to variable-length
|
|
+@cindex variable-length records, converting to fixed-length
|
|
+Set the conversion block size to @var{bytes}.
|
|
+When converting variable-length records to fixed-length ones
|
|
+(@option{conv=block}) or the reverse (@option{conv=unblock}),
|
|
+use @var{bytes} as the fixed record length.
|
|
+
|
|
+@item skip=@var{blocks}
|
|
+@opindex skip
|
|
+Skip @var{blocks} @samp{ibs}-byte blocks in the input file before copying.
|
|
+
|
|
+@item seek=@var{blocks}
|
|
+@opindex seek
|
|
+Skip @var{blocks} @samp{obs}-byte blocks in the output file before copying.
|
|
+
|
|
+@item count=@var{blocks}
|
|
+@opindex count
|
|
+Copy @var{blocks} @samp{ibs}-byte blocks from the input file, instead
|
|
+of everything until the end of the file.
|
|
+
|
|
+@item status=noxfer
|
|
+@opindex status
|
|
+Do not print the overall transfer rate and volume statistics
|
|
+that normally make up the third status line when @command{dd} exits.
|
|
+
|
|
+@item conv=@var{conversion}[,@var{conversion}]@dots{}
|
|
+@opindex conv
|
|
+Convert the file as specified by the @var{conversion} argument(s).
|
|
+(No spaces around any comma(s).)
|
|
+
|
|
+Conversions:
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item ascii
|
|
+@opindex ascii@r{, converting to}
|
|
+Convert @acronym{EBCDIC} to @acronym{ASCII},
|
|
+using the conversion table specified by @acronym{POSIX}.
|
|
+This provides a 1:1 translation for all 256 bytes.
|
|
+
|
|
+@item ebcdic
|
|
+@opindex ebcdic@r{, converting to}
|
|
+Convert @acronym{ASCII} to @acronym{EBCDIC}.
|
|
+This is the inverse of the @samp{ascii} conversion.
|
|
+
|
|
+@item ibm
|
|
+@opindex alternate ebcdic@r{, converting to}
|
|
+Convert @acronym{ASCII} to alternate @acronym{EBCDIC},
|
|
+using the alternate conversion table specified by @acronym{POSIX}.
|
|
+This is not a 1:1 translation, but reflects common historical practice
|
|
+for @samp{~}, @samp{[}, and @samp{]}.
|
|
+
|
|
+The @samp{ascii}, @samp{ebcdic}, and @samp{ibm} conversions are
|
|
+mutually exclusive.
|
|
+
|
|
+@item block
|
|
+@opindex block @r{(space-padding)}
|
|
+For each line in the input, output @samp{cbs} bytes, replacing the
|
|
+input newline with a space and padding with spaces as necessary.
|
|
+
|
|
+@item unblock
|
|
+@opindex unblock
|
|
+Remove any trailing spaces in each @samp{cbs}-sized input block,
|
|
+and append a newline.
|
|
+
|
|
+The @samp{block} and @samp{unblock} conversions are mutually exclusive.
|
|
+
|
|
+@item lcase
|
|
+@opindex lcase@r{, converting to}
|
|
+Change uppercase letters to lowercase.
|
|
+
|
|
+@item ucase
|
|
+@opindex ucase@r{, converting to}
|
|
+Change lowercase letters to uppercase.
|
|
+
|
|
+The @samp{lcase} and @samp{ucase} conversions are mutually exclusive.
|
|
+
|
|
+@item swab
|
|
+@opindex swab @r{(byte-swapping)}
|
|
+@cindex byte-swapping
|
|
+Swap every pair of input bytes. @sc{gnu} @command{dd}, unlike others, works
|
|
+when an odd number of bytes are read---the last byte is simply copied
|
|
+(since there is nothing to swap it with).
|
|
+
|
|
+@item noerror
|
|
+@opindex noerror
|
|
+@cindex read errors, ignoring
|
|
+Continue after read errors.
|
|
+
|
|
+@item nocreat
|
|
+@opindex nocreat
|
|
+@cindex creating output file, avoiding
|
|
+Do not create the output file; the output file must already exist.
|
|
+
|
|
+@item excl
|
|
+@opindex excl
|
|
+@cindex creating output file, requiring
|
|
+Fail if the output file already exists; @command{dd} must create the
|
|
+output file itself.
|
|
+
|
|
+The @samp{excl} and @samp{nocreat} conversions are mutually exclusive.
|
|
+
|
|
+@item notrunc
|
|
+@opindex notrunc
|
|
+@cindex truncating output file, avoiding
|
|
+Do not truncate the output file.
|
|
+
|
|
+@item sync
|
|
+@opindex sync @r{(padding with @acronym{ASCII} @sc{nul}s)}
|
|
+Pad every input block to size of @samp{ibs} with trailing zero bytes.
|
|
+When used with @samp{block} or @samp{unblock}, pad with spaces instead of
|
|
+zero bytes.
|
|
+
|
|
+@item fdatasync
|
|
+@opindex fdatasync
|
|
+@cindex synchronized data writes, before finishing
|
|
+Synchronize output data just before finishing. This forces a physical
|
|
+write of output data.
|
|
+
|
|
+@item fsync
|
|
+@opindex fsync
|
|
+@cindex synchronized data and metadata writes, before finishing
|
|
+Synchronize output data and metadata just before finishing. This
|
|
+forces a physical write of output data and metadata.
|
|
+
|
|
+@end table
|
|
+
|
|
+@item iflag=@var{flag}[,@var{flag}]@dots{}
|
|
+@opindex iflag
|
|
+Access the input file using the flags specified by the @var{flag}
|
|
+argument(s). (No spaces around any comma(s).)
|
|
+
|
|
+@item oflag=@var{flag}[,@var{flag}]@dots{}
|
|
+@opindex oflag
|
|
+Access the output file using the flags specified by the @var{flag}
|
|
+argument(s). (No spaces around any comma(s).)
|
|
+
|
|
+Here are the flags. Not every flag is supported on every operating
|
|
+system.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item append
|
|
+@opindex append
|
|
+@cindex appending to the output file
|
|
+Write in append mode, so that even if some other process is writing to
|
|
+this file, every @command{dd} write will append to the current
|
|
+contents of the file. This flag makes sense only for output.
|
|
+If you combine this flag with the @samp{of=@var{file}} operand,
|
|
+you should also specify @samp{conv=notrunc} unless you want the
|
|
+output file to be truncated before being appended to.
|
|
+
|
|
+@item cio
|
|
+@opindex cio
|
|
+@cindex concurrent I/O
|
|
+Use concurrent I/O mode for data. This mode performs direct I/O
|
|
+and drops the @acronym{POSIX} requirement to serialize all I/O to the same file.
|
|
+A file cannot be opened in CIO mode and with a standard open at the
|
|
+same time.
|
|
+
|
|
+@item direct
|
|
+@opindex direct
|
|
+@cindex direct I/O
|
|
+Use direct I/O for data, avoiding the buffer cache.
|
|
+Note that the kernel may impose restrictions on read or write buffer sizes.
|
|
+For example, with an ext4 destination file system and a linux-based kernel,
|
|
+using @samp{oflag=direct} will cause writes to fail with @code{EINVAL} if the
|
|
+output buffer size is not a multiple of 512.
|
|
+
|
|
+@item directory
|
|
+@opindex directory
|
|
+@cindex directory I/O
|
|
+
|
|
+Fail unless the file is a directory. Most operating systems do not
|
|
+allow I/O to a directory, so this flag has limited utility.
|
|
+
|
|
+@item dsync
|
|
+@opindex dsync
|
|
+@cindex synchronized data reads
|
|
+Use synchronized I/O for data. For the output file, this forces a
|
|
+physical write of output data on each write. For the input file,
|
|
+this flag can matter when reading from a remote file that has been
|
|
+written to synchronously by some other process. Metadata (e.g.,
|
|
+last-access and last-modified time) is not necessarily synchronized.
|
|
+
|
|
+@item sync
|
|
+@opindex sync
|
|
+@cindex synchronized data and metadata I/O
|
|
+Use synchronized I/O for both data and metadata.
|
|
+
|
|
+@item nonblock
|
|
+@opindex nonblock
|
|
+@cindex nonblocking I/O
|
|
+Use non-blocking I/O.
|
|
+
|
|
+@item noatime
|
|
+@opindex noatime
|
|
+@cindex access time
|
|
+Do not update the file's access time.
|
|
+Some older file systems silently ignore this flag, so it is a good
|
|
+idea to test it on your files before relying on it.
|
|
+
|
|
+@item noctty
|
|
+@opindex noctty
|
|
+@cindex controlling terminal
|
|
+Do not assign the file to be a controlling terminal for @command{dd}.
|
|
+This has no effect when the file is not a terminal.
|
|
+On many hosts (e.g., @acronym{GNU}/Linux hosts), this option has no effect
|
|
+at all.
|
|
+
|
|
+@item nofollow
|
|
+@opindex nofollow
|
|
+@cindex symbolic links, following
|
|
+Do not follow symbolic links.
|
|
+
|
|
+@item nolinks
|
|
+@opindex nolinks
|
|
+@cindex hard links
|
|
+Fail if the file has multiple hard links.
|
|
+
|
|
+@item binary
|
|
+@opindex binary
|
|
+@cindex binary I/O
|
|
+Use binary I/O. This option has an effect only on nonstandard
|
|
+platforms that distinguish binary from text I/O.
|
|
+
|
|
+@item text
|
|
+@opindex text
|
|
+@cindex text I/O
|
|
+Use text I/O. Like @samp{binary}, this option has no effect on
|
|
+standard platforms.
|
|
+
|
|
+@item fullblock
|
|
+@opindex fullblock
|
|
+Accumulate full blocks from input. The @code{read} system call
|
|
+may return early if a full block is not available.
|
|
+When that happens, continue calling @code{read} to fill the remainder
|
|
+of the block.
|
|
+This flag can be used only with @code{iflag}.
|
|
+
|
|
+@end table
|
|
+
|
|
+These flags are not supported on all systems, and @samp{dd} rejects
|
|
+attempts to use them when they are not supported. When reading from
|
|
+standard input or writing to standard output, the @samp{nofollow} and
|
|
+@samp{noctty} flags should not be specified, and the other flags
|
|
+(e.g., @samp{nonblock}) can affect how other processes behave with the
|
|
+affected file descriptors, even after @command{dd} exits.
|
|
+
|
|
+@end table
|
|
+
|
|
+@cindex multipliers after numbers
|
|
+The numeric-valued strings above (@var{bytes} and @var{blocks}) can be
|
|
+followed by a multiplier: @samp{b}=512, @samp{c}=1,
|
|
+@samp{w}=2, @samp{x@var{m}}=@var{m}, or any of the
|
|
+standard block size suffixes like @samp{k}=1024 (@pxref{Block size}).
|
|
+
|
|
+Use different @command{dd} invocations to use different block sizes for
|
|
+skipping and I/O@. For example, the following shell commands copy data
|
|
+in 512 KiB blocks between a disk and a tape, but do not save or restore a
|
|
+4 KiB label at the start of the disk:
|
|
+
|
|
+@example
|
|
+disk=/dev/rdsk/c0t1d0s2
|
|
+tape=/dev/rmt/0
|
|
+
|
|
+# Copy all but the label from disk to tape.
|
|
+(dd bs=4k skip=1 count=0 && dd bs=512k) <$disk >$tape
|
|
+
|
|
+# Copy from tape back to disk, but leave the disk label alone.
|
|
+(dd bs=4k seek=1 count=0 && dd bs=512k) <$tape >$disk
|
|
+@end example
|
|
+
|
|
+Sending an @samp{INFO} signal to a running @command{dd}
|
|
+process makes it print I/O statistics to standard error
|
|
+and then resume copying. In the example below,
|
|
+@command{dd} is run in the background to copy 10 million blocks.
|
|
+The @command{kill} command makes it output intermediate I/O statistics,
|
|
+and when @command{dd} completes normally or is killed by the
|
|
+@code{SIGINT} signal, it outputs the final statistics.
|
|
+
|
|
+@example
|
|
+$ dd if=/dev/zero of=/dev/null count=10MB & pid=$!
|
|
+$ kill -s INFO $pid; wait $pid
|
|
+3385223+0 records in
|
|
+3385223+0 records out
|
|
+1733234176 bytes (1.7 GB) copied, 6.42173 seconds, 270 MB/s
|
|
+10000000+0 records in
|
|
+10000000+0 records out
|
|
+5120000000 bytes (5.1 GB) copied, 18.913 seconds, 271 MB/s
|
|
+@end example
|
|
+
|
|
+@vindex POSIXLY_CORRECT
|
|
+On systems lacking the @samp{INFO} signal @command{dd} responds to the
|
|
+@samp{USR1} signal instead, unless the @env{POSIXLY_CORRECT}
|
|
+environment variable is set.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node install invocation
|
|
+@section @command{install}: Copy files and set attributes
|
|
+
|
|
+@pindex install
|
|
+@cindex copying files and setting attributes
|
|
+
|
|
+@command{install} copies files while setting their file mode bits and, if
|
|
+possible, their owner and group. Synopses:
|
|
+
|
|
+@example
|
|
+install [@var{option}]@dots{} [-T] @var{source} @var{dest}
|
|
+install [@var{option}]@dots{} @var{source}@dots{} @var{directory}
|
|
+install [@var{option}]@dots{} -t @var{directory} @var{source}@dots{}
|
|
+install [@var{option}]@dots{} -d @var{directory}@dots{}
|
|
+@end example
|
|
+
|
|
+@itemize @bullet
|
|
+@item
|
|
+If two file names are given, @command{install} copies the first file to the
|
|
+second.
|
|
+
|
|
+@item
|
|
+If the @option{--target-directory} (@option{-t}) option is given, or
|
|
+failing that if the last file is a directory and the
|
|
+@option{--no-target-directory} (@option{-T}) option is not given,
|
|
+@command{install} copies each @var{source} file to the specified
|
|
+directory, using the @var{source}s' names.
|
|
+
|
|
+@item
|
|
+If the @option{--directory} (@option{-d}) option is given,
|
|
+@command{install} creates each @var{directory} and any missing parent
|
|
+directories. Parent directories are created with mode
|
|
+@samp{u=rwx,go=rx} (755), regardless of the @option{-m} option or the
|
|
+current umask. @xref{Directory Setuid and Setgid}, for how the
|
|
+set-user-ID and set-group-ID bits of parent directories are inherited.
|
|
+@end itemize
|
|
+
|
|
+@cindex Makefiles, installing programs in
|
|
+@command{install} is similar to @command{cp}, but allows you to control the
|
|
+attributes of destination files. It is typically used in Makefiles to
|
|
+copy programs into their destination directories. It refuses to copy
|
|
+files onto themselves.
|
|
+
|
|
+@cindex extended attributes, xattr
|
|
+@command{install} never preserves extended attributes (xattr).
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@optBackup
|
|
+
|
|
+@item -C
|
|
+@itemx --compare
|
|
+@opindex -C
|
|
+@opindex --compare
|
|
+Compare each pair of source and destination files, and if the destination has
|
|
+identical content and any specified owner, group, permissions, and possibly
|
|
+SELinux context, then do not modify the destination at all.
|
|
+
|
|
+@item -c
|
|
+@opindex -c
|
|
+Ignored; for compatibility with old Unix versions of @command{install}.
|
|
+
|
|
+@item -D
|
|
+@opindex -D
|
|
+Create any missing parent directories of @var{dest},
|
|
+then copy @var{source} to @var{dest}.
|
|
+This option is ignored if a destination directory is specified
|
|
+via @option{--target-directory=DIR}.
|
|
+
|
|
+@item -d
|
|
+@itemx --directory
|
|
+@opindex -d
|
|
+@opindex --directory
|
|
+@cindex directories, creating with given attributes
|
|
+@cindex parent directories, creating missing
|
|
+@cindex leading directories, creating missing
|
|
+Create any missing parent directories, giving them the default
|
|
+attributes. Then create each given directory, setting their owner,
|
|
+group and mode as given on the command line or to the defaults.
|
|
+
|
|
+@item -g @var{group}
|
|
+@itemx --group=@var{group}
|
|
+@opindex -g
|
|
+@opindex --group
|
|
+@cindex group ownership of installed files, setting
|
|
+Set the group ownership of installed files or directories to
|
|
+@var{group}. The default is the process's current group. @var{group}
|
|
+may be either a group name or a numeric group ID.
|
|
+
|
|
+@item -m @var{mode}
|
|
+@itemx --mode=@var{mode}
|
|
+@opindex -m
|
|
+@opindex --mode
|
|
+@cindex permissions of installed files, setting
|
|
+Set the file mode bits for the installed file or directory to @var{mode},
|
|
+which can be either an octal number, or a symbolic mode as in
|
|
+@command{chmod}, with @samp{a=} (no access allowed to anyone) as the
|
|
+point of departure (@pxref{File permissions}).
|
|
+The default mode is @samp{u=rwx,go=rx,a-s}---read, write, and
|
|
+execute for the owner, read and execute for group and other, and with
|
|
+set-user-ID and set-group-ID disabled.
|
|
+This default is not quite the same as @samp{755}, since it disables
|
|
+instead of preserving set-user-ID and set-group-ID on directories.
|
|
+@xref{Directory Setuid and Setgid}.
|
|
+
|
|
+@item -o @var{owner}
|
|
+@itemx --owner=@var{owner}
|
|
+@opindex -o
|
|
+@opindex --owner
|
|
+@cindex ownership of installed files, setting
|
|
+@cindex appropriate privileges
|
|
+@vindex root @r{as default owner}
|
|
+If @command{install} has appropriate privileges (is run as root), set the
|
|
+ownership of installed files or directories to @var{owner}. The default
|
|
+is @code{root}. @var{owner} may be either a user name or a numeric user
|
|
+ID.
|
|
+
|
|
+@item --preserve-context
|
|
+@opindex --preserve-context
|
|
+@cindex SELinux
|
|
+@cindex security context
|
|
+Preserve the SELinux security context of files and directories.
|
|
+Failure to preserve the context in all of the files or directories
|
|
+will result in an exit status of 1. If SELinux is disabled then
|
|
+print a warning and ignore the option.
|
|
+
|
|
+@item -p
|
|
+@itemx --preserve-timestamps
|
|
+@opindex -p
|
|
+@opindex --preserve-timestamps
|
|
+@cindex timestamps of installed files, preserving
|
|
+Set the time of last access and the time of last modification of each
|
|
+installed file to match those of each corresponding original file.
|
|
+When a file is installed without this option, its last access and
|
|
+last modification times are both set to the time of installation.
|
|
+This option is useful if you want to use the last modification times
|
|
+of installed files to keep track of when they were last built as opposed
|
|
+to when they were last installed.
|
|
+
|
|
+@item -s
|
|
+@itemx --strip
|
|
+@opindex -s
|
|
+@opindex --strip
|
|
+@cindex symbol table information, stripping
|
|
+@cindex stripping symbol table information
|
|
+Strip the symbol tables from installed binary executables.
|
|
+
|
|
+@itemx --strip-program=@var{program}
|
|
+@opindex --strip-program
|
|
+@cindex symbol table information, stripping, program
|
|
+Program used to strip binaries.
|
|
+
|
|
+@optBackupSuffix
|
|
+
|
|
+@optTargetDirectory
|
|
+
|
|
+@optNoTargetDirectory
|
|
+
|
|
+@item -v
|
|
+@itemx --verbose
|
|
+@opindex -v
|
|
+@opindex --verbose
|
|
+Print the name of each file before copying it.
|
|
+
|
|
+@item -Z @var{context}
|
|
+@itemx --context=@var{context}
|
|
+@opindex -Z
|
|
+@opindex --context
|
|
+@cindex SELinux
|
|
+@cindex security context
|
|
+Set the default SELinux security context to be used for any
|
|
+created files and directories. If SELinux is disabled then
|
|
+print a warning and ignore the option.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node mv invocation
|
|
+@section @command{mv}: Move (rename) files
|
|
+
|
|
+@pindex mv
|
|
+
|
|
+@command{mv} moves or renames files (or directories). Synopses:
|
|
+
|
|
+@example
|
|
+mv [@var{option}]@dots{} [-T] @var{source} @var{dest}
|
|
+mv [@var{option}]@dots{} @var{source}@dots{} @var{directory}
|
|
+mv [@var{option}]@dots{} -t @var{directory} @var{source}@dots{}
|
|
+@end example
|
|
+
|
|
+@itemize @bullet
|
|
+@item
|
|
+If two file names are given, @command{mv} moves the first file to the
|
|
+second.
|
|
+
|
|
+@item
|
|
+If the @option{--target-directory} (@option{-t}) option is given, or
|
|
+failing that if the last file is a directory and the
|
|
+@option{--no-target-directory} (@option{-T}) option is not given,
|
|
+@command{mv} moves each @var{source} file to the specified
|
|
+directory, using the @var{source}s' names.
|
|
+@end itemize
|
|
+
|
|
+@command{mv} can move any type of file from one file system to another.
|
|
+Prior to version @code{4.0} of the fileutils,
|
|
+@command{mv} could move only regular files between file systems.
|
|
+For example, now @command{mv} can move an entire directory hierarchy
|
|
+including special device files from one partition to another. It first
|
|
+uses some of the same code that's used by @code{cp -a} to copy the
|
|
+requested directories and files, then (assuming the copy succeeded)
|
|
+it removes the originals. If the copy fails, then the part that was
|
|
+copied to the destination partition is removed. If you were to copy
|
|
+three directories from one partition to another and the copy of the first
|
|
+directory succeeded, but the second didn't, the first would be left on
|
|
+the destination partition and the second and third would be left on the
|
|
+original partition.
|
|
+
|
|
+@cindex extended attributes, xattr
|
|
+@command{mv} always tries to copy extended attributes (xattr).
|
|
+
|
|
+@cindex prompting, and @command{mv}
|
|
+If a destination file exists but is normally unwritable, standard input
|
|
+is a terminal, and the @option{-f} or @option{--force} option is not given,
|
|
+@command{mv} prompts the user for whether to replace the file. (You might
|
|
+own the file, or have write permission on its directory.) If the
|
|
+response is not affirmative, the file is skipped.
|
|
+
|
|
+@emph{Warning}: Avoid specifying a source name with a trailing slash,
|
|
+when it might be a symlink to a directory.
|
|
+Otherwise, @command{mv} may do something very surprising, since
|
|
+its behavior depends on the underlying rename system call.
|
|
+On a system with a modern Linux-based kernel, it fails with @code{errno=ENOTDIR}.
|
|
+However, on other systems (at least FreeBSD 6.1 and Solaris 10) it silently
|
|
+renames not the symlink but rather the directory referenced by the symlink.
|
|
+@xref{Trailing slashes}.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@optBackup
|
|
+
|
|
+@item -f
|
|
+@itemx --force
|
|
+@opindex -f
|
|
+@opindex --force
|
|
+@cindex prompts, omitting
|
|
+Do not prompt the user before removing a destination file.
|
|
+@macro mvOptsIfn
|
|
+If you specify more than one of the @option{-i}, @option{-f}, @option{-n}
|
|
+options, only the final one takes effect.
|
|
+@end macro
|
|
+@mvOptsIfn
|
|
+
|
|
+@item -i
|
|
+@itemx --interactive
|
|
+@opindex -i
|
|
+@opindex --interactive
|
|
+@cindex prompts, forcing
|
|
+Prompt whether to overwrite each existing destination file, regardless
|
|
+of its permissions.
|
|
+If the response is not affirmative, the file is skipped.
|
|
+@mvOptsIfn
|
|
+
|
|
+@item -n
|
|
+@itemx --no-clobber
|
|
+@opindex -n
|
|
+@opindex --no-clobber
|
|
+@cindex prompts, omitting
|
|
+Do not overwrite an existing file.
|
|
+@mvOptsIfn
|
|
+This option is mutually exclusive with @option{-b} or @option{--backup} option.
|
|
+
|
|
+@item -u
|
|
+@itemx --update
|
|
+@opindex -u
|
|
+@opindex --update
|
|
+@cindex newer files, moving only
|
|
+Do not move a non-directory that has an existing destination with the
|
|
+same or newer modification time.
|
|
+If the move is across file system boundaries, the comparison is to the
|
|
+source time stamp truncated to the resolutions of the destination file
|
|
+system and of the system calls used to update time stamps; this avoids
|
|
+duplicate work if several @samp{mv -u} commands are executed with the
|
|
+same source and destination.
|
|
+
|
|
+@item -v
|
|
+@itemx --verbose
|
|
+@opindex -v
|
|
+@opindex --verbose
|
|
+Print the name of each file before moving it.
|
|
+
|
|
+@optStripTrailingSlashes
|
|
+
|
|
+@optBackupSuffix
|
|
+
|
|
+@optTargetDirectory
|
|
+
|
|
+@optNoTargetDirectory
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node rm invocation
|
|
+@section @command{rm}: Remove files or directories
|
|
+
|
|
+@pindex rm
|
|
+@cindex removing files or directories
|
|
+
|
|
+@command{rm} removes each given @var{file}. By default, it does not remove
|
|
+directories. Synopsis:
|
|
+
|
|
+@example
|
|
+rm [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+@cindex prompting, and @command{rm}
|
|
+If the @option{-I} or @option{--interactive=once} option is given,
|
|
+and there are more than three files or the @option{-r}, @option{-R},
|
|
+or @option{--recursive} are given, then @command{rm} prompts the user
|
|
+for whether to proceed with the entire operation. If the response is
|
|
+not affirmative, the entire command is aborted.
|
|
+
|
|
+Otherwise, if a file is unwritable, standard input is a terminal, and
|
|
+the @option{-f} or @option{--force} option is not given, or the
|
|
+@option{-i} or @option{--interactive=always} option @emph{is} given,
|
|
+@command{rm} prompts the user for whether to remove the file.
|
|
+If the response is not affirmative, the file is skipped.
|
|
+
|
|
+Any attempt to remove a file whose last file name component is
|
|
+@file{.} or @file{..} is rejected without any prompting.
|
|
+
|
|
+@emph{Warning}: If you use @command{rm} to remove a file, it is usually
|
|
+possible to recover the contents of that file. If you want more assurance
|
|
+that the contents are truly unrecoverable, consider using @command{shred}.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -f
|
|
+@itemx --force
|
|
+@opindex -f
|
|
+@opindex --force
|
|
+Ignore nonexistent files and never prompt the user.
|
|
+Ignore any previous @option{--interactive} (@option{-i}) option.
|
|
+
|
|
+@item -i
|
|
+@opindex -i
|
|
+Prompt whether to remove each file.
|
|
+If the response is not affirmative, the file is skipped.
|
|
+Ignore any previous @option{--force} (@option{-f}) option.
|
|
+Equivalent to @option{--interactive=always}.
|
|
+
|
|
+@item -I
|
|
+@opindex -I
|
|
+Prompt once whether to proceed with the command, if more than three
|
|
+files are named or if a recursive removal is requested. Ignore any
|
|
+previous @option{--force} (@option{-f}) option. Equivalent to
|
|
+@option{--interactive=once}.
|
|
+
|
|
+@itemx --interactive [=@var{when}]
|
|
+@opindex --interactive
|
|
+Specify when to issue an interactive prompt. @var{when} may be
|
|
+omitted, or one of:
|
|
+@itemize @bullet
|
|
+@item never
|
|
+@vindex never @r{interactive option}
|
|
+- Do not prompt at all.
|
|
+@item once
|
|
+@vindex once @r{interactive option}
|
|
+- Prompt once if more than three files are named or if a recursive
|
|
+removal is requested. Equivalent to @option{-I}.
|
|
+@item always
|
|
+@vindex always @r{interactive option}
|
|
+- Prompt for every file being removed. Equivalent to @option{-i}.
|
|
+@end itemize
|
|
+@option{--interactive} with no @var{when} is equivalent to
|
|
+@option{--interactive=always}.
|
|
+
|
|
+@itemx --one-file-system
|
|
+@opindex --one-file-system
|
|
+@cindex one file system, restricting @command{rm} to
|
|
+When removing a hierarchy recursively, skip any directory that is on a
|
|
+file system different from that of the corresponding command line argument.
|
|
+
|
|
+This option is useful when removing a build ``chroot'' hierarchy,
|
|
+which normally contains no valuable data. However, it is not uncommon
|
|
+to bind-mount @file{/home} into such a hierarchy, to make it easier to
|
|
+use one's start-up file. The catch is that it's easy to forget to
|
|
+unmount @file{/home}. Then, when you use @command{rm -rf} to remove
|
|
+your normally throw-away chroot, that command will remove everything
|
|
+under @file{/home}, too.
|
|
+Use the @option{--one-file-system} option, and it will
|
|
+warn about and skip directories on other file systems.
|
|
+Of course, this will not save your @file{/home} if it and your
|
|
+chroot happen to be on the same file system.
|
|
+
|
|
+@itemx --preserve-root
|
|
+@opindex --preserve-root
|
|
+@cindex root directory, disallow recursive destruction
|
|
+Fail upon any attempt to remove the root directory, @file{/},
|
|
+when used with the @option{--recursive} option.
|
|
+This is the default behavior.
|
|
+@xref{Treating / specially}.
|
|
+
|
|
+@itemx --no-preserve-root
|
|
+@opindex --no-preserve-root
|
|
+@cindex root directory, allow recursive destruction
|
|
+Do not treat @file{/} specially when removing recursively.
|
|
+This option is not recommended unless you really want to
|
|
+remove all the files on your computer.
|
|
+@xref{Treating / specially}.
|
|
+
|
|
+@item -r
|
|
+@itemx -R
|
|
+@itemx --recursive
|
|
+@opindex -r
|
|
+@opindex -R
|
|
+@opindex --recursive
|
|
+@cindex directories, removing (recursively)
|
|
+Remove the listed directories and their contents recursively.
|
|
+
|
|
+@item -v
|
|
+@itemx --verbose
|
|
+@opindex -v
|
|
+@opindex --verbose
|
|
+Print the name of each file before removing it.
|
|
+
|
|
+@end table
|
|
+
|
|
+@cindex files beginning with @samp{-}, removing
|
|
+@cindex @samp{-}, removing files beginning with
|
|
+One common question is how to remove files whose names begin with a
|
|
+@samp{-}. @sc{gnu} @command{rm}, like every program that uses the @code{getopt}
|
|
+function to parse its arguments, lets you use the @samp{--} option to
|
|
+indicate that all following arguments are non-options. To remove a file
|
|
+called @file{-f} in the current directory, you could type either:
|
|
+
|
|
+@example
|
|
+rm -- -f
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+or:
|
|
+
|
|
+@example
|
|
+rm ./-f
|
|
+@end example
|
|
+
|
|
+@opindex - @r{and Unix @command{rm}}
|
|
+The Unix @command{rm} program's use of a single @samp{-} for this purpose
|
|
+predates the development of the getopt standard syntax.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node shred invocation
|
|
+@section @command{shred}: Remove files more securely
|
|
+
|
|
+@pindex shred
|
|
+@cindex data, erasing
|
|
+@cindex erasing data
|
|
+
|
|
+@command{shred} overwrites devices or files, to help prevent even
|
|
+very expensive hardware from recovering the data.
|
|
+
|
|
+Ordinarily when you remove a file (@pxref{rm invocation}), the data is
|
|
+not actually destroyed. Only the index listing where the file is
|
|
+stored is destroyed, and the storage is made available for reuse.
|
|
+There are undelete utilities that will attempt to reconstruct the index
|
|
+and can bring the file back if the parts were not reused.
|
|
+
|
|
+On a busy system with a nearly-full drive, space can get reused in a few
|
|
+seconds. But there is no way to know for sure. If you have sensitive
|
|
+data, you may want to be sure that recovery is not possible by actually
|
|
+overwriting the file with non-sensitive data.
|
|
+
|
|
+However, even after doing that, it is possible to take the disk back
|
|
+to a laboratory and use a lot of sensitive (and expensive) equipment
|
|
+to look for the faint ``echoes'' of the original data underneath the
|
|
+overwritten data. If the data has only been overwritten once, it's not
|
|
+even that hard.
|
|
+
|
|
+The best way to remove something irretrievably is to destroy the media
|
|
+it's on with acid, melt it down, or the like. For cheap removable media
|
|
+like floppy disks, this is the preferred method. However, hard drives
|
|
+are expensive and hard to melt, so the @command{shred} utility tries
|
|
+to achieve a similar effect non-destructively.
|
|
+
|
|
+This uses many overwrite passes, with the data patterns chosen to
|
|
+maximize the damage they do to the old data. While this will work on
|
|
+floppies, the patterns are designed for best effect on hard drives.
|
|
+For more details, see the source code and Peter Gutmann's paper
|
|
+@uref{http://www.cs.auckland.ac.nz/~pgut001/pubs/secure_del.html,
|
|
+@cite{Secure Deletion of Data from Magnetic and Solid-State Memory}},
|
|
+from the proceedings of the Sixth @acronym{USENIX} Security Symposium (San Jose,
|
|
+California, July 22--25, 1996).
|
|
+
|
|
+@strong{Please note} that @command{shred} relies on a very important assumption:
|
|
+that the file system overwrites data in place. This is the traditional
|
|
+way to do things, but many modern file system designs do not satisfy this
|
|
+assumption. Exceptions include:
|
|
+
|
|
+@itemize @bullet
|
|
+
|
|
+@item
|
|
+Log-structured or journaled file systems, such as those supplied with
|
|
+AIX and Solaris, and JFS, ReiserFS, XFS, Ext3 (in @code{data=journal} mode),
|
|
+BFS, NTFS, etc.@: when they are configured to journal @emph{data}.
|
|
+
|
|
+@item
|
|
+File systems that write redundant data and carry on even if some writes
|
|
+fail, such as RAID-based file systems.
|
|
+
|
|
+@item
|
|
+File systems that make snapshots, such as Network Appliance's NFS server.
|
|
+
|
|
+@item
|
|
+File systems that cache in temporary locations, such as NFS version 3
|
|
+clients.
|
|
+
|
|
+@item
|
|
+Compressed file systems.
|
|
+@end itemize
|
|
+
|
|
+In the particular case of ext3 file systems, the above disclaimer applies (and
|
|
+@command{shred} is thus of limited effectiveness) only in @code{data=journal}
|
|
+mode, which journals file data in addition to just metadata. In both
|
|
+the @code{data=ordered} (default) and @code{data=writeback} modes,
|
|
+@command{shred} works as usual. Ext3 journaling modes can be changed
|
|
+by adding the @code{data=something} option to the mount options for a
|
|
+particular file system in the @file{/etc/fstab} file, as documented in
|
|
+the mount man page (man mount).
|
|
+
|
|
+If you are not sure how your file system operates, then you should assume
|
|
+that it does not overwrite data in place, which means that shred cannot
|
|
+reliably operate on regular files in your file system.
|
|
+
|
|
+Generally speaking, it is more reliable to shred a device than a file,
|
|
+since this bypasses the problem of file system design mentioned above.
|
|
+However, even shredding devices is not always completely reliable. For
|
|
+example, most disks map out bad sectors invisibly to the application; if
|
|
+the bad sectors contain sensitive data, @command{shred} won't be able to
|
|
+destroy it.
|
|
+
|
|
+@command{shred} makes no attempt to detect or report this problem, just as
|
|
+it makes no attempt to do anything about backups. However, since it is
|
|
+more reliable to shred devices than files, @command{shred} by default does
|
|
+not truncate or remove the output file. This default is more suitable
|
|
+for devices, which typically cannot be truncated and should not be
|
|
+removed.
|
|
+
|
|
+Finally, consider the risk of backups and mirrors.
|
|
+File system backups and remote mirrors may contain copies of the
|
|
+file that cannot be removed, and that will allow a shredded file
|
|
+to be recovered later. So if you keep any data you may later want
|
|
+to destroy using @command{shred}, be sure that it is not backed up or mirrored.
|
|
+
|
|
+@example
|
|
+shred [@var{option}]@dots{} @var{file}[@dots{}]
|
|
+@end example
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -f
|
|
+@itemx --force
|
|
+@opindex -f
|
|
+@opindex --force
|
|
+@cindex force deletion
|
|
+Override file permissions if necessary to allow overwriting.
|
|
+
|
|
+@item -@var{number}
|
|
+@itemx -n @var{number}
|
|
+@itemx --iterations=@var{number}
|
|
+@opindex -n @var{number}
|
|
+@opindex --iterations=@var{number}
|
|
+@cindex iterations, selecting the number of
|
|
+By default, @command{shred} uses @value{SHRED_DEFAULT_PASSES} passes of
|
|
+overwrite. You can reduce this to save time, or increase it if you think it's
|
|
+appropriate. After 25 passes all of the internal overwrite patterns will have
|
|
+been used at least once.
|
|
+
|
|
+@item --random-source=@var{file}
|
|
+@opindex --random-source
|
|
+@cindex random source for shredding
|
|
+Use @var{file} as a source of random data used to overwrite and to
|
|
+choose pass ordering. @xref{Random sources}.
|
|
+
|
|
+@item -s @var{bytes}
|
|
+@itemx --size=@var{bytes}
|
|
+@opindex -s @var{bytes}
|
|
+@opindex --size=@var{bytes}
|
|
+@cindex size of file to shred
|
|
+Shred the first @var{bytes} bytes of the file. The default is to shred
|
|
+the whole file. @var{bytes} can be followed by a size specification like
|
|
+@samp{K}, @samp{M}, or @samp{G} to specify a multiple. @xref{Block size}.
|
|
+
|
|
+@item -u
|
|
+@itemx --remove
|
|
+@opindex -u
|
|
+@opindex --remove
|
|
+@cindex removing files after shredding
|
|
+After shredding a file, truncate it (if possible) and then remove it.
|
|
+If a file has multiple links, only the named links will be removed.
|
|
+
|
|
+@item -v
|
|
+@itemx --verbose
|
|
+@opindex -v
|
|
+@opindex --verbose
|
|
+Display to standard error all status updates as sterilization proceeds.
|
|
+
|
|
+@item -x
|
|
+@itemx --exact
|
|
+@opindex -x
|
|
+@opindex --exact
|
|
+By default, @command{shred} rounds the size of a regular file up to the next
|
|
+multiple of the file system block size to fully erase the last block of the file.
|
|
+Use @option{--exact} to suppress that behavior.
|
|
+Thus, by default if you shred a 10-byte regular file on a system with 512-byte
|
|
+blocks, the resulting file will be 512 bytes long. With this option,
|
|
+shred does not increase the apparent size of the file.
|
|
+
|
|
+@item -z
|
|
+@itemx --zero
|
|
+@opindex -z
|
|
+@opindex --zero
|
|
+Normally, the last pass that @command{shred} writes is made up of
|
|
+random data. If this would be conspicuous on your hard drive (for
|
|
+example, because it looks like encrypted data), or you just think
|
|
+it's tidier, the @option{--zero} option adds an additional overwrite pass with
|
|
+all zero bits. This is in addition to the number of passes specified
|
|
+by the @option{--iterations} option.
|
|
+
|
|
+@end table
|
|
+
|
|
+You might use the following command to erase all trace of the
|
|
+file system you'd created on the floppy disk in your first drive.
|
|
+That command takes about 20 minutes to erase a ``1.44MB'' (actually
|
|
+1440 KiB) floppy.
|
|
+
|
|
+@example
|
|
+shred --verbose /dev/fd0
|
|
+@end example
|
|
+
|
|
+Similarly, to erase all data on a selected partition of
|
|
+your hard disk, you could give a command like this:
|
|
+
|
|
+@example
|
|
+shred --verbose /dev/sda5
|
|
+@end example
|
|
+
|
|
+A @var{file} of @samp{-} denotes standard output.
|
|
+The intended use of this is to shred a removed temporary file.
|
|
+For example:
|
|
+
|
|
+@example
|
|
+i=`tempfile -m 0600`
|
|
+exec 3<>"$i"
|
|
+rm -- "$i"
|
|
+echo "Hello, world" >&3
|
|
+shred - >&3
|
|
+exec 3>-
|
|
+@end example
|
|
+
|
|
+However, the command @samp{shred - >file} does not shred the contents
|
|
+of @var{file}, since the shell truncates @var{file} before invoking
|
|
+@command{shred}. Use the command @samp{shred file} or (if using a
|
|
+Bourne-compatible shell) the command @samp{shred - 1<>file} instead.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node Special file types
|
|
+@chapter Special file types
|
|
+
|
|
+@cindex special file types
|
|
+@cindex file types, special
|
|
+
|
|
+This chapter describes commands which create special types of files (and
|
|
+@command{rmdir}, which removes directories, one special file type).
|
|
+
|
|
+@cindex special file types
|
|
+@cindex file types
|
|
+Although Unix-like operating systems have markedly fewer special file
|
|
+types than others, not @emph{everything} can be treated only as the
|
|
+undifferentiated byte stream of @dfn{normal files}. For example, when a
|
|
+file is created or removed, the system must record this information,
|
|
+which it does in a @dfn{directory}---a special type of file. Although
|
|
+you can read directories as normal files, if you're curious, in order
|
|
+for the system to do its job it must impose a structure, a certain
|
|
+order, on the bytes of the file. Thus it is a ``special'' type of file.
|
|
+
|
|
+Besides directories, other special file types include named pipes
|
|
+(FIFOs), symbolic links, sockets, and so-called @dfn{special files}.
|
|
+
|
|
+@menu
|
|
+* 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 the unlink syscall
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node link invocation
|
|
+@section @command{link}: Make a hard link via the link syscall
|
|
+
|
|
+@pindex link
|
|
+@cindex links, creating
|
|
+@cindex hard links, creating
|
|
+@cindex creating links (hard only)
|
|
+
|
|
+@command{link} creates a single hard link at a time.
|
|
+It is a minimalist interface to the system-provided
|
|
+@code{link} function. @xref{Hard Links, , , libc,
|
|
+The GNU C Library Reference Manual}.
|
|
+It avoids the bells and whistles of the more commonly-used
|
|
+@command{ln} command (@pxref{ln invocation}).
|
|
+Synopsis:
|
|
+
|
|
+@example
|
|
+link @var{filename} @var{linkname}
|
|
+@end example
|
|
+
|
|
+@var{filename} must specify an existing file, and @var{linkname}
|
|
+must specify a nonexistent entry in an existing directory.
|
|
+@command{link} simply calls @code{link (@var{filename}, @var{linkname})}
|
|
+to create the link.
|
|
+
|
|
+On a @acronym{GNU} system, this command acts like @samp{ln --directory
|
|
+--no-target-directory @var{filename} @var{linkname}}. However, the
|
|
+@option{--directory} and @option{--no-target-directory} options are
|
|
+not specified by @acronym{POSIX}, and the @command{link} command is
|
|
+more portable in practice.
|
|
+
|
|
+If @var{filename} is a symbolic link, it is unspecified whether
|
|
+@var{linkname} will be a hard link to the symbolic link or to the
|
|
+target of the symbolic link. Use @command{ln -P} or @command{ln -L}
|
|
+to specify which behavior is desired.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node ln invocation
|
|
+@section @command{ln}: Make links between files
|
|
+
|
|
+@pindex ln
|
|
+@cindex links, creating
|
|
+@cindex hard links, creating
|
|
+@cindex symbolic (soft) links, creating
|
|
+@cindex creating links (hard or soft)
|
|
+
|
|
+@cindex file systems and hard links
|
|
+@command{ln} makes links between files. By default, it makes hard links;
|
|
+with the @option{-s} option, it makes symbolic (or @dfn{soft}) links.
|
|
+Synopses:
|
|
+
|
|
+@example
|
|
+ln [@var{option}]@dots{} [-T] @var{target} @var{linkname}
|
|
+ln [@var{option}]@dots{} @var{target}
|
|
+ln [@var{option}]@dots{} @var{target}@dots{} @var{directory}
|
|
+ln [@var{option}]@dots{} -t @var{directory} @var{target}@dots{}
|
|
+@end example
|
|
+
|
|
+@itemize @bullet
|
|
+
|
|
+@item
|
|
+If two file names are given, @command{ln} creates a link to the first
|
|
+file from the second.
|
|
+
|
|
+@item
|
|
+If one @var{target} is given, @command{ln} creates a link to that file
|
|
+in the current directory.
|
|
+
|
|
+@item
|
|
+If the @option{--target-directory} (@option{-t}) option is given, or
|
|
+failing that if the last file is a directory and the
|
|
+@option{--no-target-directory} (@option{-T}) option is not given,
|
|
+@command{ln} creates a link to each @var{target} file in the specified
|
|
+directory, using the @var{target}s' names.
|
|
+
|
|
+@end itemize
|
|
+
|
|
+Normally @command{ln} does not remove existing files. Use the
|
|
+@option{--force} (@option{-f}) option to remove them unconditionally,
|
|
+the @option{--interactive} (@option{-i}) option to remove them
|
|
+conditionally, and the @option{--backup} (@option{-b}) option to
|
|
+rename them.
|
|
+
|
|
+@cindex hard link, defined
|
|
+@cindex inode, and hard links
|
|
+A @dfn{hard link} is another name for an existing file; the link and the
|
|
+original are indistinguishable. Technically speaking, they share the
|
|
+same inode, and the inode contains all the information about a
|
|
+file---indeed, it is not incorrect to say that the inode @emph{is} the
|
|
+file. Most systems prohibit making a hard link to
|
|
+a directory; on those where it is allowed, only the super-user can do
|
|
+so (and with caution, since creating a cycle will cause problems to many
|
|
+other utilities). Hard links cannot cross file system boundaries. (These
|
|
+restrictions are not mandated by @acronym{POSIX}, however.)
|
|
+
|
|
+@cindex dereferencing symbolic links
|
|
+@cindex symbolic link, defined
|
|
+@dfn{Symbolic links} (@dfn{symlinks} for short), on the other hand, are
|
|
+a special file type (which not all kernels support: System V release 3
|
|
+(and older) systems lack symlinks) in which the link file actually
|
|
+refers to a different file, by name. When most operations (opening,
|
|
+reading, writing, and so on) are passed the symbolic link file, the
|
|
+kernel automatically @dfn{dereferences} the link and operates on the
|
|
+target of the link. But some operations (e.g., removing) work on the
|
|
+link file itself, rather than on its target. The owner and group of a
|
|
+symlink are not significant to file access performed through
|
|
+the link, but do have implications on deleting a symbolic link from a
|
|
+directory with the restricted deletion bit set. On the GNU system,
|
|
+the mode of a symlink has no significance and cannot be changed, but
|
|
+on some BSD systems, the mode can be changed and will affect whether
|
|
+the symlink will be traversed in file name resolution. @xref{Symbolic Links,,,
|
|
+libc, The GNU C Library Reference Manual}.
|
|
+
|
|
+Symbolic links can contain arbitrary strings; a @dfn{dangling symlink}
|
|
+occurs when the string in the symlink does not resolve to a file.
|
|
+There are no restrictions against creating dangling symbolic links.
|
|
+There are trade-offs to using absolute or relative symlinks. An
|
|
+absolute symlink always points to the same file, even if the directory
|
|
+containing the link is moved. However, if the symlink is visible from
|
|
+more than one machine (such as on a networked file system), the file
|
|
+pointed to might not always be the same. A relative symbolic link is
|
|
+resolved in relation to the directory that contains the link, and is
|
|
+often useful in referring to files on the same device without regards
|
|
+to what name that device is mounted on when accessed via networked
|
|
+machines.
|
|
+
|
|
+When creating a relative symlink in a different location than the
|
|
+current directory, the resolution of the symlink will be different
|
|
+than the resolution of the same string from the current directory.
|
|
+Therefore, many users prefer to first change directories to the
|
|
+location where the relative symlink will be created, so that
|
|
+tab-completion or other file resolution will find the same target as
|
|
+what will be placed in the symlink.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@optBackup
|
|
+
|
|
+@item -d
|
|
+@itemx -F
|
|
+@itemx --directory
|
|
+@opindex -d
|
|
+@opindex -F
|
|
+@opindex --directory
|
|
+@cindex hard links to directories
|
|
+Allow users with appropriate privileges to attempt to make hard links
|
|
+to directories.
|
|
+However, note that this will probably fail due to
|
|
+system restrictions, even for the super-user.
|
|
+
|
|
+@item -f
|
|
+@itemx --force
|
|
+@opindex -f
|
|
+@opindex --force
|
|
+Remove existing destination files.
|
|
+
|
|
+@item -i
|
|
+@itemx --interactive
|
|
+@opindex -i
|
|
+@opindex --interactive
|
|
+@cindex prompting, and @command{ln}
|
|
+Prompt whether to remove existing destination files.
|
|
+
|
|
+@item -L
|
|
+@itemx --logical
|
|
+@opindex -L
|
|
+@opindex --logical
|
|
+If @option{-s} is not in effect, and the source file is a symbolic
|
|
+link, create the hard link to the file referred to by the symbolic
|
|
+link, rather than the symbolic link itself.
|
|
+
|
|
+@item -n
|
|
+@itemx --no-dereference
|
|
+@opindex -n
|
|
+@opindex --no-dereference
|
|
+Do not treat the last operand specially when it is a symbolic link to
|
|
+a directory. Instead, treat it as if it were a normal file.
|
|
+
|
|
+When the destination is an actual directory (not a symlink to one),
|
|
+there is no ambiguity. The link is created in that directory.
|
|
+But when the specified destination is a symlink to a directory,
|
|
+there are two ways to treat the user's request. @command{ln} can
|
|
+treat the destination just as it would a normal directory and create
|
|
+the link in it. On the other hand, the destination can be viewed as a
|
|
+non-directory---as the symlink itself. In that case, @command{ln}
|
|
+must delete or backup that symlink before creating the new link.
|
|
+The default is to treat a destination that is a symlink to a directory
|
|
+just like a directory.
|
|
+
|
|
+This option is weaker than the @option{--no-target-directory}
|
|
+(@option{-T}) option, so it has no effect if both options are given.
|
|
+
|
|
+@item -P
|
|
+@itemx --physical
|
|
+@opindex -P
|
|
+@opindex --physical
|
|
+If @option{-s} is not in effect, and the source file is a symbolic
|
|
+link, create the hard link to the symbolic link itself. On platforms
|
|
+where this is not supported by the kernel, this option creates a
|
|
+symbolic link with identical contents; since symbolic link contents
|
|
+cannot be edited, any file name resolution performed through either
|
|
+link will be the same as if a hard link had been created.
|
|
+
|
|
+@item -s
|
|
+@itemx --symbolic
|
|
+@opindex -s
|
|
+@opindex --symbolic
|
|
+Make symbolic links instead of hard links. This option merely produces
|
|
+an error message on systems that do not support symbolic links.
|
|
+
|
|
+@optBackupSuffix
|
|
+
|
|
+@optTargetDirectory
|
|
+
|
|
+@optNoTargetDirectory
|
|
+
|
|
+@item -v
|
|
+@itemx --verbose
|
|
+@opindex -v
|
|
+@opindex --verbose
|
|
+Print the name of each file after linking it successfully.
|
|
+
|
|
+@end table
|
|
+
|
|
+@cindex hard links to symbolic links
|
|
+@cindex symbolic links and @command{ln}
|
|
+If @option{-L} and @option{-P} are both given, the last one takes
|
|
+precedence. If @option{-s} is also given, @option{-L} and @option{-P}
|
|
+are silently ignored. If neither option is given, then this
|
|
+implementation defaults to @option{-P} if the system @code{link} supports
|
|
+hard links to symbolic links (such as the GNU system), and @option{-L}
|
|
+if @code{link} follows symbolic links (such as on BSD).
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+Examples:
|
|
+
|
|
+@smallexample
|
|
+Bad Example:
|
|
+
|
|
+# Create link ../a pointing to a in that directory.
|
|
+# Not really useful because it points to itself.
|
|
+ln -s a ..
|
|
+
|
|
+Better Example:
|
|
+
|
|
+# Change to the target before creating symlinks to avoid being confused.
|
|
+cd ..
|
|
+ln -s adir/a .
|
|
+
|
|
+Bad Example:
|
|
+
|
|
+# Hard coded file names don't move well.
|
|
+ln -s $(pwd)/a /some/dir/
|
|
+
|
|
+Better Example:
|
|
+
|
|
+# Relative file names survive directory moves and also
|
|
+# work across networked file systems.
|
|
+ln -s afile anotherfile
|
|
+ln -s ../adir/afile yetanotherfile
|
|
+@end smallexample
|
|
+
|
|
+
|
|
+@node mkdir invocation
|
|
+@section @command{mkdir}: Make directories
|
|
+
|
|
+@pindex mkdir
|
|
+@cindex directories, creating
|
|
+@cindex creating directories
|
|
+
|
|
+@command{mkdir} creates directories with the specified names. Synopsis:
|
|
+
|
|
+@example
|
|
+mkdir [@var{option}]@dots{} @var{name}@dots{}
|
|
+@end example
|
|
+
|
|
+@command{mkdir} creates each directory @var{name} in the order given.
|
|
+It reports an error if @var{name} already exists, unless the
|
|
+@option{-p} option is given and @var{name} is a directory.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -m @var{mode}
|
|
+@itemx --mode=@var{mode}
|
|
+@opindex -m
|
|
+@opindex --mode
|
|
+@cindex modes of created directories, setting
|
|
+Set the file permission bits of created directories to @var{mode},
|
|
+which uses the same syntax as
|
|
+in @command{chmod} and uses @samp{a=rwx} (read, write and execute allowed for
|
|
+everyone) for the point of the departure. @xref{File permissions}.
|
|
+
|
|
+Normally the directory has the desired file mode bits at the moment it
|
|
+is created. As a @acronym{GNU} extension, @var{mode} may also mention
|
|
+special mode bits, but in this case there may be a temporary window
|
|
+during which the directory exists but its special mode bits are
|
|
+incorrect. @xref{Directory Setuid and Setgid}, for how the
|
|
+set-user-ID and set-group-ID bits of directories are inherited unless
|
|
+overridden in this way.
|
|
+
|
|
+@item -p
|
|
+@itemx --parents
|
|
+@opindex -p
|
|
+@opindex --parents
|
|
+@cindex parent directories, creating
|
|
+Make any missing parent directories for each argument, setting their
|
|
+file permission bits to the umask modified by @samp{u+wx}. Ignore
|
|
+existing parent directories, and do not change their file permission
|
|
+bits.
|
|
+
|
|
+To set the file permission bits of any newly-created parent
|
|
+directories to a value that includes @samp{u+wx}, you can set the
|
|
+umask before invoking @command{mkdir}. For example, if the shell
|
|
+command @samp{(umask u=rwx,go=rx; mkdir -p P/Q)} creates the parent
|
|
+@file{P} it sets the parent's permission bits to @samp{u=rwx,go=rx}.
|
|
+To set a parent's special mode bits as well, you can invoke
|
|
+@command{chmod} after @command{mkdir}. @xref{Directory Setuid and
|
|
+Setgid}, for how the set-user-ID and set-group-ID bits of
|
|
+newly-created parent directories are inherited.
|
|
+
|
|
+@item -v
|
|
+@itemx --verbose
|
|
+@opindex -v
|
|
+@opindex --verbose
|
|
+Print a message for each created directory. This is most useful with
|
|
+@option{--parents}.
|
|
+
|
|
+@item -Z @var{context}
|
|
+@itemx --context=@var{context}
|
|
+@opindex -Z
|
|
+@opindex --context
|
|
+@cindex SELinux
|
|
+@cindex security context
|
|
+Set the default SELinux security context to be used for created directories.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node mkfifo invocation
|
|
+@section @command{mkfifo}: Make FIFOs (named pipes)
|
|
+
|
|
+@pindex mkfifo
|
|
+@cindex FIFOs, creating
|
|
+@cindex named pipes, creating
|
|
+@cindex creating FIFOs (named pipes)
|
|
+
|
|
+@command{mkfifo} creates FIFOs (also called @dfn{named pipes}) with the
|
|
+specified names. Synopsis:
|
|
+
|
|
+@example
|
|
+mkfifo [@var{option}] @var{name}@dots{}
|
|
+@end example
|
|
+
|
|
+A @dfn{FIFO} is a special file type that permits independent processes
|
|
+to communicate. One process opens the FIFO file for writing, and
|
|
+another for reading, after which data can flow as with the usual
|
|
+anonymous pipe in shells or elsewhere.
|
|
+
|
|
+The program accepts the following option. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -m @var{mode}
|
|
+@itemx --mode=@var{mode}
|
|
+@opindex -m
|
|
+@opindex --mode
|
|
+@cindex modes of created FIFOs, setting
|
|
+Set the mode of created FIFOs to @var{mode}, which is symbolic as in
|
|
+@command{chmod} and uses @samp{a=rw} (read and write allowed for everyone)
|
|
+for the point of departure. @var{mode} should specify only file
|
|
+permission bits. @xref{File permissions}.
|
|
+
|
|
+@item -Z @var{context}
|
|
+@itemx --context=@var{context}
|
|
+@opindex -Z
|
|
+@opindex --context
|
|
+@cindex SELinux
|
|
+@cindex security context
|
|
+Set the default SELinux security context to be used for created FIFOs.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node mknod invocation
|
|
+@section @command{mknod}: Make block or character special files
|
|
+
|
|
+@pindex mknod
|
|
+@cindex block special files, creating
|
|
+@cindex character special files, creating
|
|
+
|
|
+@command{mknod} creates a FIFO, character special file, or block special
|
|
+file with the specified name. Synopsis:
|
|
+
|
|
+@example
|
|
+mknod [@var{option}]@dots{} @var{name} @var{type} [@var{major} @var{minor}]
|
|
+@end example
|
|
+
|
|
+@cindex special files
|
|
+@cindex block special files
|
|
+@cindex character special files
|
|
+Unlike the phrase ``special file type'' above, the term @dfn{special
|
|
+file} has a technical meaning on Unix: something that can generate or
|
|
+receive data. Usually this corresponds to a physical piece of hardware,
|
|
+e.g., a printer or a disk. (These files are typically created at
|
|
+system-configuration time.) The @command{mknod} command is what creates
|
|
+files of this type. Such devices can be read either a character at a
|
|
+time or a ``block'' (many characters) at a time, hence we say there are
|
|
+@dfn{block special} files and @dfn{character special} files.
|
|
+
|
|
+@c mknod is a shell built-in at least with OpenBSD's /bin/sh
|
|
+@mayConflictWithShellBuiltIn{mknod}
|
|
+
|
|
+The arguments after @var{name} specify the type of file to make:
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item p
|
|
+@opindex p @r{for FIFO file}
|
|
+for a FIFO
|
|
+
|
|
+@item b
|
|
+@opindex b @r{for block special file}
|
|
+for a block special file
|
|
+
|
|
+@item c
|
|
+@c Don't document the `u' option -- it's just a synonym for `c'.
|
|
+@c Do *any* versions of mknod still use it?
|
|
+@c @itemx u
|
|
+@opindex c @r{for character special file}
|
|
+@c @opindex u @r{for character special file}
|
|
+for a character special file
|
|
+
|
|
+@end table
|
|
+
|
|
+When making a block or character special file, the major and minor
|
|
+device numbers must be given after the file type.
|
|
+If a major or minor device number begins with @samp{0x} or @samp{0X},
|
|
+it is interpreted as hexadecimal; otherwise, if it begins with @samp{0},
|
|
+as octal; otherwise, as decimal.
|
|
+
|
|
+The program accepts the following option. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -m @var{mode}
|
|
+@itemx --mode=@var{mode}
|
|
+@opindex -m
|
|
+@opindex --mode
|
|
+Set the mode of created files to @var{mode}, which is symbolic as in
|
|
+@command{chmod} and uses @samp{a=rw} as the point of departure.
|
|
+@var{mode} should specify only file permission bits.
|
|
+@xref{File permissions}.
|
|
+
|
|
+@item -Z @var{context}
|
|
+@itemx --context=@var{context}
|
|
+@opindex -Z
|
|
+@opindex --context
|
|
+@cindex SELinux
|
|
+@cindex security context
|
|
+Set the default SELinux security context to be used for created files.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node readlink invocation
|
|
+@section @command{readlink}: Print value of a symlink or canonical file name
|
|
+
|
|
+@pindex readlink
|
|
+@cindex displaying value of a symbolic link
|
|
+@cindex canonical file name
|
|
+@cindex canonicalize a file name
|
|
+@pindex realpath
|
|
+@findex realpath
|
|
+
|
|
+@command{readlink} may work in one of two supported modes:
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item Readlink mode
|
|
+
|
|
+@command{readlink} outputs the value of the given symbolic link.
|
|
+If @command{readlink} is invoked with an argument other than the name
|
|
+of a symbolic link, it produces no output and exits with a nonzero exit code.
|
|
+
|
|
+@item Canonicalize mode
|
|
+
|
|
+@command{readlink} outputs the absolute name of the given file which contains
|
|
+no @file{.}, @file{..} components nor any repeated separators
|
|
+(@file{/}) or symbolic links.
|
|
+
|
|
+@end table
|
|
+
|
|
+@example
|
|
+readlink [@var{option}] @var{file}
|
|
+@end example
|
|
+
|
|
+By default, @command{readlink} operates in readlink mode.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -f
|
|
+@itemx --canonicalize
|
|
+@opindex -f
|
|
+@opindex --canonicalize
|
|
+Activate canonicalize mode.
|
|
+If any component of the file name except the last one is missing or unavailable,
|
|
+@command{readlink} produces no output and exits with a nonzero exit
|
|
+code. A trailing slash is ignored.
|
|
+
|
|
+@item -e
|
|
+@itemx --canonicalize-existing
|
|
+@opindex -e
|
|
+@opindex --canonicalize-existing
|
|
+Activate canonicalize mode.
|
|
+If any component is missing or unavailable, @command{readlink} produces
|
|
+no output and exits with a nonzero exit code. A trailing slash
|
|
+requires that the name resolve to a directory.
|
|
+
|
|
+@item -m
|
|
+@itemx --canonicalize-missing
|
|
+@opindex -m
|
|
+@opindex --canonicalize-missing
|
|
+Activate canonicalize mode.
|
|
+If any component is missing or unavailable, @command{readlink} treats it
|
|
+as a directory.
|
|
+
|
|
+@item -n
|
|
+@itemx --no-newline
|
|
+@opindex -n
|
|
+@opindex --no-newline
|
|
+Do not output the trailing newline.
|
|
+
|
|
+@item -s
|
|
+@itemx -q
|
|
+@itemx --silent
|
|
+@itemx --quiet
|
|
+@opindex -s
|
|
+@opindex -q
|
|
+@opindex --silent
|
|
+@opindex --quiet
|
|
+Suppress most error messages.
|
|
+
|
|
+@item -v
|
|
+@itemx --verbose
|
|
+@opindex -v
|
|
+@opindex --verbose
|
|
+Report error messages.
|
|
+
|
|
+@end table
|
|
+
|
|
+The @command{readlink} utility first appeared in OpenBSD 2.1.
|
|
+
|
|
+There is a @command{realpath} command on some systems
|
|
+which operates like @command{readlink} in canonicalize mode.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node rmdir invocation
|
|
+@section @command{rmdir}: Remove empty directories
|
|
+
|
|
+@pindex rmdir
|
|
+@cindex removing empty directories
|
|
+@cindex directories, removing empty
|
|
+
|
|
+@command{rmdir} removes empty directories. Synopsis:
|
|
+
|
|
+@example
|
|
+rmdir [@var{option}]@dots{} @var{directory}@dots{}
|
|
+@end example
|
|
+
|
|
+If any @var{directory} argument does not refer to an existing empty
|
|
+directory, it is an error.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item --ignore-fail-on-non-empty
|
|
+@opindex --ignore-fail-on-non-empty
|
|
+@cindex directory deletion, ignoring failures
|
|
+Ignore each failure to remove a directory that is solely because
|
|
+the directory is non-empty.
|
|
+
|
|
+@item -p
|
|
+@itemx --parents
|
|
+@opindex -p
|
|
+@opindex --parents
|
|
+@cindex parent directories, removing
|
|
+Remove @var{directory}, then try to remove each component of @var{directory}.
|
|
+So, for example, @samp{rmdir -p a/b/c} is similar to @samp{rmdir a/b/c a/b a}.
|
|
+As such, it fails if any of those directories turns out not to be empty.
|
|
+Use the @option{--ignore-fail-on-non-empty} option to make it so such
|
|
+a failure does not evoke a diagnostic and does not cause @command{rmdir} to
|
|
+exit unsuccessfully.
|
|
+
|
|
+@item -v
|
|
+@itemx --verbose
|
|
+@opindex -v
|
|
+@opindex --verbose
|
|
+@cindex directory deletion, reporting
|
|
+Give a diagnostic for each successful removal.
|
|
+@var{directory} is removed.
|
|
+
|
|
+@end table
|
|
+
|
|
+@xref{rm invocation}, for how to remove non-empty directories (recursively).
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node unlink invocation
|
|
+@section @command{unlink}: Remove files via the unlink syscall
|
|
+
|
|
+@pindex unlink
|
|
+@cindex removing files or directories (via the unlink syscall)
|
|
+
|
|
+@command{unlink} deletes a single specified file name.
|
|
+It is a minimalist interface to the system-provided
|
|
+@code{unlink} function. @xref{Deleting Files, , , libc,
|
|
+The GNU C Library Reference Manual}. Synopsis:
|
|
+It avoids the bells and whistles of the more commonly-used
|
|
+@command{rm} command (@pxref{rm invocation}).
|
|
+
|
|
+@example
|
|
+unlink @var{filename}
|
|
+@end example
|
|
+
|
|
+On some systems @code{unlink} can be used to delete the name of a
|
|
+directory. On others, it can be used that way only by a privileged user.
|
|
+In the GNU system @code{unlink} can never delete the name of a directory.
|
|
+
|
|
+The @command{unlink} command honors the @option{--help} and
|
|
+@option{--version} options. To remove a file whose name begins with
|
|
+@samp{-}, prefix the name with @samp{./}, e.g., @samp{unlink ./--help}.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node Changing file attributes
|
|
+@chapter Changing file attributes
|
|
+
|
|
+@cindex changing file attributes
|
|
+@cindex file attributes, changing
|
|
+@cindex attributes, file
|
|
+
|
|
+A file is not merely its contents, a name, and a file type
|
|
+(@pxref{Special file types}). A file also has an owner (a user ID), a
|
|
+group (a group ID), permissions (what the owner can do with the file,
|
|
+what people in the group can do, and what everyone else can do), various
|
|
+timestamps, and other information. Collectively, we call these a file's
|
|
+@dfn{attributes}.
|
|
+
|
|
+These commands change file attributes.
|
|
+
|
|
+@menu
|
|
+* chgrp invocation:: Change file groups.
|
|
+* chmod invocation:: Change access permissions.
|
|
+* chown invocation:: Change file owners and groups.
|
|
+* touch invocation:: Change file timestamps.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node chown invocation
|
|
+@section @command{chown}: Change file owner and group
|
|
+
|
|
+@pindex chown
|
|
+@cindex file ownership, changing
|
|
+@cindex group ownership, changing
|
|
+@cindex changing file ownership
|
|
+@cindex changing group ownership
|
|
+
|
|
+@command{chown} changes the user and/or group ownership of each given @var{file}
|
|
+to @var{new-owner} or to the user and group of an existing reference file.
|
|
+Synopsis:
|
|
+
|
|
+@example
|
|
+chown [@var{option}]@dots{} @{@var{new-owner} | --reference=@var{ref_file}@} @var{file}@dots{}
|
|
+@end example
|
|
+
|
|
+If used, @var{new-owner} specifies the new owner and/or group as follows
|
|
+(with no embedded white space):
|
|
+
|
|
+@example
|
|
+[@var{owner}] [ : [@var{group}] ]
|
|
+@end example
|
|
+
|
|
+Specifically:
|
|
+
|
|
+@table @var
|
|
+@item owner
|
|
+If only an @var{owner} (a user name or numeric user ID) is given, that
|
|
+user is made the owner of each given file, and the files' group is not
|
|
+changed.
|
|
+
|
|
+@item owner@samp{:}group
|
|
+If the @var{owner} is followed by a colon and a @var{group} (a
|
|
+group name or numeric group ID), with no spaces between them, the group
|
|
+ownership of the files is changed as well (to @var{group}).
|
|
+
|
|
+@item owner@samp{:}
|
|
+If a colon but no group name follows @var{owner}, that user is
|
|
+made the owner of the files and the group of the files is changed to
|
|
+@var{owner}'s login group.
|
|
+
|
|
+@item @samp{:}group
|
|
+If the colon and following @var{group} are given, but the owner
|
|
+is omitted, only the group of the files is changed; in this case,
|
|
+@command{chown} performs the same function as @command{chgrp}.
|
|
+
|
|
+@item @samp{:}
|
|
+If only a colon is given, or if @var{new-owner} is empty, neither the
|
|
+owner nor the group is changed.
|
|
+
|
|
+@end table
|
|
+
|
|
+If @var{owner} or @var{group} is intended to represent a numeric user
|
|
+or group ID, then you may specify it with a leading @samp{+}.
|
|
+@xref{Disambiguating names and IDs}.
|
|
+
|
|
+Some older scripts may still use @samp{.} in place of the @samp{:} separator.
|
|
+@acronym{POSIX} 1003.1-2001 (@pxref{Standards conformance}) does not
|
|
+require support for that, but for backward compatibility @acronym{GNU}
|
|
+@command{chown} supports @samp{.} so long as no ambiguity results.
|
|
+New scripts should avoid the use of @samp{.} because it is not
|
|
+portable, and because it has undesirable results if the entire
|
|
+@var{owner@samp{.}group} happens to identify a user whose name
|
|
+contains @samp{.}.
|
|
+
|
|
+The @command{chown} command sometimes clears the set-user-ID or
|
|
+set-group-ID permission bits. This behavior depends on the policy and
|
|
+functionality of the underlying @code{chown} system call, which may
|
|
+make system-dependent file mode modifications outside the control of
|
|
+the @command{chown} command. For example, the @command{chown} command
|
|
+might not affect those bits when invoked by a user with appropriate
|
|
+privileges, or when the
|
|
+bits signify some function other than executable permission (e.g.,
|
|
+mandatory locking).
|
|
+When in doubt, check the underlying system behavior.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -c
|
|
+@itemx --changes
|
|
+@opindex -c
|
|
+@opindex --changes
|
|
+@cindex changed owners, verbosely describing
|
|
+Verbosely describe the action for each @var{file} whose ownership
|
|
+actually changes.
|
|
+
|
|
+@item -f
|
|
+@itemx --silent
|
|
+@itemx --quiet
|
|
+@opindex -f
|
|
+@opindex --silent
|
|
+@opindex --quiet
|
|
+@cindex error messages, omitting
|
|
+Do not print error messages about files whose ownership cannot be
|
|
+changed.
|
|
+
|
|
+@itemx @w{@kbd{--from}=@var{old-owner}}
|
|
+@opindex --from
|
|
+@cindex symbolic links, changing owner
|
|
+Change a @var{file}'s ownership only if it has current attributes specified
|
|
+by @var{old-owner}. @var{old-owner} has the same form as @var{new-owner}
|
|
+described above.
|
|
+This option is useful primarily from a security standpoint in that
|
|
+it narrows considerably the window of potential abuse.
|
|
+For example, to reflect a user ID numbering change for one user's files
|
|
+without an option like this, @code{root} might run
|
|
+
|
|
+@smallexample
|
|
+find / -owner OLDUSER -print0 | xargs -0 chown -h NEWUSER
|
|
+@end smallexample
|
|
+
|
|
+But that is dangerous because the interval between when the @command{find}
|
|
+tests the existing file's owner and when the @command{chown} is actually run
|
|
+may be quite large.
|
|
+One way to narrow the gap would be to invoke chown for each file
|
|
+as it is found:
|
|
+
|
|
+@example
|
|
+find / -owner OLDUSER -exec chown -h NEWUSER @{@} \;
|
|
+@end example
|
|
+
|
|
+But that is very slow if there are many affected files.
|
|
+With this option, it is safer (the gap is narrower still)
|
|
+though still not perfect:
|
|
+
|
|
+@example
|
|
+chown -h -R --from=OLDUSER NEWUSER /
|
|
+@end example
|
|
+
|
|
+@item --dereference
|
|
+@opindex --dereference
|
|
+@cindex symbolic links, changing owner
|
|
+@findex lchown
|
|
+Do not act on symbolic links themselves but rather on what they point to.
|
|
+This is the default.
|
|
+
|
|
+@item -h
|
|
+@itemx --no-dereference
|
|
+@opindex -h
|
|
+@opindex --no-dereference
|
|
+@cindex symbolic links, changing owner
|
|
+@findex lchown
|
|
+Act on symbolic links themselves instead of what they point to.
|
|
+This mode relies on the @code{lchown} system call.
|
|
+On systems that do not provide the @code{lchown} system call,
|
|
+@command{chown} fails when a file specified on the command line
|
|
+is a symbolic link.
|
|
+By default, no diagnostic is issued for symbolic links encountered
|
|
+during a recursive traversal, but see @option{--verbose}.
|
|
+
|
|
+@itemx --preserve-root
|
|
+@opindex --preserve-root
|
|
+@cindex root directory, disallow recursive modification
|
|
+Fail upon any attempt to recursively change the root directory, @file{/}.
|
|
+Without @option{--recursive}, this option has no effect.
|
|
+@xref{Treating / specially}.
|
|
+
|
|
+@itemx --no-preserve-root
|
|
+@opindex --no-preserve-root
|
|
+@cindex root directory, allow recursive modification
|
|
+Cancel the effect of any preceding @option{--preserve-root} option.
|
|
+@xref{Treating / specially}.
|
|
+
|
|
+@item --reference=@var{ref_file}
|
|
+@opindex --reference
|
|
+Change the user and group of each @var{file} to be the same as those of
|
|
+@var{ref_file}. If @var{ref_file} is a symbolic link, do not use the
|
|
+user and group of the symbolic link, but rather those of the file it
|
|
+refers to.
|
|
+
|
|
+@item -v
|
|
+@itemx --verbose
|
|
+@opindex -v
|
|
+@opindex --verbose
|
|
+Output a diagnostic for every file processed.
|
|
+If a symbolic link is encountered during a recursive traversal
|
|
+on a system without the @code{lchown} system call, and @option{--no-dereference}
|
|
+is in effect, then issue a diagnostic saying neither the symbolic link nor
|
|
+its referent is being changed.
|
|
+
|
|
+@item -R
|
|
+@itemx --recursive
|
|
+@opindex -R
|
|
+@opindex --recursive
|
|
+@cindex recursively changing file ownership
|
|
+Recursively change ownership of directories and their contents.
|
|
+
|
|
+@choptH
|
|
+@xref{Traversing symlinks}.
|
|
+
|
|
+@choptL
|
|
+@xref{Traversing symlinks}.
|
|
+
|
|
+@choptP
|
|
+@xref{Traversing symlinks}.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+Examples:
|
|
+
|
|
+@smallexample
|
|
+# Change the owner of /u to "root".
|
|
+chown root /u
|
|
+
|
|
+# Likewise, but also change its group to "staff".
|
|
+chown root:staff /u
|
|
+
|
|
+# Change the owner of /u and subfiles to "root".
|
|
+chown -hR root /u
|
|
+@end smallexample
|
|
+
|
|
+
|
|
+@node chgrp invocation
|
|
+@section @command{chgrp}: Change group ownership
|
|
+
|
|
+@pindex chgrp
|
|
+@cindex group ownership, changing
|
|
+@cindex changing group ownership
|
|
+
|
|
+@command{chgrp} changes the group ownership of each given @var{file}
|
|
+to @var{group} (which can be either a group name or a numeric group ID)
|
|
+or to the group of an existing reference file. Synopsis:
|
|
+
|
|
+@example
|
|
+chgrp [@var{option}]@dots{} @{@var{group} | --reference=@var{ref_file}@} @var{file}@dots{}
|
|
+@end example
|
|
+
|
|
+If @var{group} is intended to represent a
|
|
+numeric group ID, then you may specify it with a leading @samp{+}.
|
|
+@xref{Disambiguating names and IDs}.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -c
|
|
+@itemx --changes
|
|
+@opindex -c
|
|
+@opindex --changes
|
|
+@cindex changed files, verbosely describing
|
|
+Verbosely describe the action for each @var{file} whose group actually
|
|
+changes.
|
|
+
|
|
+@item -f
|
|
+@itemx --silent
|
|
+@itemx --quiet
|
|
+@opindex -f
|
|
+@opindex --silent
|
|
+@opindex --quiet
|
|
+@cindex error messages, omitting
|
|
+Do not print error messages about files whose group cannot be
|
|
+changed.
|
|
+
|
|
+@item --dereference
|
|
+@opindex --dereference
|
|
+@cindex symbolic links, changing owner
|
|
+@findex lchown
|
|
+Do not act on symbolic links themselves but rather on what they point to.
|
|
+This is the default.
|
|
+
|
|
+@item -h
|
|
+@itemx --no-dereference
|
|
+@opindex -h
|
|
+@opindex --no-dereference
|
|
+@cindex symbolic links, changing group
|
|
+@findex lchown
|
|
+Act on symbolic links themselves instead of what they point to.
|
|
+This mode relies on the @code{lchown} system call.
|
|
+On systems that do not provide the @code{lchown} system call,
|
|
+@command{chgrp} fails when a file specified on the command line
|
|
+is a symbolic link.
|
|
+By default, no diagnostic is issued for symbolic links encountered
|
|
+during a recursive traversal, but see @option{--verbose}.
|
|
+
|
|
+@itemx --preserve-root
|
|
+@opindex --preserve-root
|
|
+@cindex root directory, disallow recursive modification
|
|
+Fail upon any attempt to recursively change the root directory, @file{/}.
|
|
+Without @option{--recursive}, this option has no effect.
|
|
+@xref{Treating / specially}.
|
|
+
|
|
+@itemx --no-preserve-root
|
|
+@opindex --no-preserve-root
|
|
+@cindex root directory, allow recursive modification
|
|
+Cancel the effect of any preceding @option{--preserve-root} option.
|
|
+@xref{Treating / specially}.
|
|
+
|
|
+@item --reference=@var{ref_file}
|
|
+@opindex --reference
|
|
+Change the group of each @var{file} to be the same as that of
|
|
+@var{ref_file}. If @var{ref_file} is a symbolic link, do not use the
|
|
+group of the symbolic link, but rather that of the file it refers to.
|
|
+
|
|
+@item -v
|
|
+@itemx --verbose
|
|
+@opindex -v
|
|
+@opindex --verbose
|
|
+Output a diagnostic for every file processed.
|
|
+If a symbolic link is encountered during a recursive traversal
|
|
+on a system without the @code{lchown} system call, and @option{--no-dereference}
|
|
+is in effect, then issue a diagnostic saying neither the symbolic link nor
|
|
+its referent is being changed.
|
|
+
|
|
+@item -R
|
|
+@itemx --recursive
|
|
+@opindex -R
|
|
+@opindex --recursive
|
|
+@cindex recursively changing group ownership
|
|
+Recursively change the group ownership of directories and their contents.
|
|
+
|
|
+@choptH
|
|
+@xref{Traversing symlinks}.
|
|
+
|
|
+@choptL
|
|
+@xref{Traversing symlinks}.
|
|
+
|
|
+@choptP
|
|
+@xref{Traversing symlinks}.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+Examples:
|
|
+
|
|
+@smallexample
|
|
+# Change the group of /u to "staff".
|
|
+chgrp staff /u
|
|
+
|
|
+# Change the group of /u and subfiles to "staff".
|
|
+chgrp -hR staff /u
|
|
+@end smallexample
|
|
+
|
|
+
|
|
+@node chmod invocation
|
|
+@section @command{chmod}: Change access permissions
|
|
+
|
|
+@pindex chmod
|
|
+@cindex changing access permissions
|
|
+@cindex access permissions, changing
|
|
+@cindex permissions, changing access
|
|
+
|
|
+@command{chmod} changes the access permissions of the named files. Synopsis:
|
|
+
|
|
+@example
|
|
+chmod [@var{option}]@dots{} @{@var{mode} | --reference=@var{ref_file}@} @var{file}@dots{}
|
|
+@end example
|
|
+
|
|
+@cindex symbolic links, permissions of
|
|
+@command{chmod} never changes the permissions of symbolic links, since
|
|
+the @command{chmod} system call cannot change their permissions.
|
|
+This is not a problem since the permissions of symbolic links are
|
|
+never used. However, for each symbolic link listed on the command
|
|
+line, @command{chmod} changes the permissions of the pointed-to file.
|
|
+In contrast, @command{chmod} ignores symbolic links encountered during
|
|
+recursive directory traversals.
|
|
+
|
|
+A successful use of @command{chmod} clears the set-group-ID bit of a
|
|
+regular file if the file's group ID does not match the user's
|
|
+effective group ID or one of the user's supplementary group IDs,
|
|
+unless the user has appropriate privileges. Additional restrictions
|
|
+may cause the set-user-ID and set-group-ID bits of @var{mode} or
|
|
+@var{ref_file} to be ignored. This behavior depends on the policy and
|
|
+functionality of the underlying @code{chmod} system call. When in
|
|
+doubt, check the underlying system behavior.
|
|
+
|
|
+If used, @var{mode} specifies the new file mode bits.
|
|
+For details, see the section on @ref{File permissions}.
|
|
+If you really want @var{mode} to have a leading @samp{-}, you should
|
|
+use @option{--} first, e.g., @samp{chmod -- -w file}. Typically,
|
|
+though, @samp{chmod a-w file} is preferable, and @command{chmod -w
|
|
+file} (without the @option{--}) complains if it behaves differently
|
|
+from what @samp{chmod a-w file} would do.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -c
|
|
+@itemx --changes
|
|
+@opindex -c
|
|
+@opindex --changes
|
|
+Verbosely describe the action for each @var{file} whose permissions
|
|
+actually changes.
|
|
+
|
|
+@item -f
|
|
+@itemx --silent
|
|
+@itemx --quiet
|
|
+@opindex -f
|
|
+@opindex --silent
|
|
+@opindex --quiet
|
|
+@cindex error messages, omitting
|
|
+Do not print error messages about files whose permissions cannot be
|
|
+changed.
|
|
+
|
|
+@itemx --preserve-root
|
|
+@opindex --preserve-root
|
|
+@cindex root directory, disallow recursive modification
|
|
+Fail upon any attempt to recursively change the root directory, @file{/}.
|
|
+Without @option{--recursive}, this option has no effect.
|
|
+@xref{Treating / specially}.
|
|
+
|
|
+@itemx --no-preserve-root
|
|
+@opindex --no-preserve-root
|
|
+@cindex root directory, allow recursive modification
|
|
+Cancel the effect of any preceding @option{--preserve-root} option.
|
|
+@xref{Treating / specially}.
|
|
+
|
|
+@item -v
|
|
+@itemx --verbose
|
|
+@opindex -v
|
|
+@opindex --verbose
|
|
+Verbosely describe the action or non-action taken for every @var{file}.
|
|
+
|
|
+@item --reference=@var{ref_file}
|
|
+@opindex --reference
|
|
+Change the mode of each @var{file} to be the same as that of @var{ref_file}.
|
|
+@xref{File permissions}.
|
|
+If @var{ref_file} is a symbolic link, do not use the mode
|
|
+of the symbolic link, but rather that of the file it refers to.
|
|
+
|
|
+@item -R
|
|
+@itemx --recursive
|
|
+@opindex -R
|
|
+@opindex --recursive
|
|
+@cindex recursively changing access permissions
|
|
+Recursively change permissions of directories and their contents.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node touch invocation
|
|
+@section @command{touch}: Change file timestamps
|
|
+
|
|
+@pindex touch
|
|
+@cindex changing file timestamps
|
|
+@cindex file timestamps, changing
|
|
+@cindex timestamps, changing file
|
|
+
|
|
+@command{touch} changes the access and/or modification times of the
|
|
+specified files. Synopsis:
|
|
+
|
|
+@example
|
|
+touch [@var{option}]@dots{} @var{file}@dots{}
|
|
+@end example
|
|
+
|
|
+@cindex empty files, creating
|
|
+Any @var{file} argument that does not exist is created empty.
|
|
+
|
|
+A @var{file} argument string of @samp{-} is handled specially and
|
|
+causes @command{touch} to change the times of the file associated with
|
|
+standard output.
|
|
+
|
|
+@cindex permissions, for changing file timestamps
|
|
+If changing both the access and modification times to the current
|
|
+time, @command{touch} can change the timestamps for files that the user
|
|
+running it does not own but has write permission for. Otherwise, the
|
|
+user must own the files.
|
|
+
|
|
+Although @command{touch} provides options for changing two of the times---the
|
|
+times of last access and modification---of a file, there is actually
|
|
+a third one as well: the inode change time. This is often referred to
|
|
+as a file's @code{ctime}.
|
|
+The inode change time represents the time when the file's meta-information
|
|
+last changed. One common example of this is when the permissions of a
|
|
+file change. Changing the permissions doesn't access the file, so
|
|
+the atime doesn't change, nor does it modify the file, so the mtime
|
|
+doesn't change. Yet, something about the file itself has changed,
|
|
+and this must be noted somewhere. This is the job of the ctime field.
|
|
+This is necessary, so that, for example, a backup program can make a
|
|
+fresh copy of the file, including the new permissions value.
|
|
+Another operation that modifies a file's ctime without affecting
|
|
+the others is renaming. In any case, it is not possible, in normal
|
|
+operations, for a user to change the ctime field to a user-specified value.
|
|
+
|
|
+@vindex TZ
|
|
+Time stamps assume the time zone rules specified by the @env{TZ}
|
|
+environment variable, or by the system default rules if @env{TZ} is
|
|
+not set. @xref{TZ Variable,, Specifying the Time Zone with @env{TZ},
|
|
+libc, The GNU C Library Reference Manual}.
|
|
+You can avoid ambiguities during
|
|
+daylight saving transitions by using @sc{utc} time stamps.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -a
|
|
+@itemx --time=atime
|
|
+@itemx --time=access
|
|
+@itemx --time=use
|
|
+@opindex -a
|
|
+@opindex --time
|
|
+@opindex atime@r{, changing}
|
|
+@opindex access @r{time, changing}
|
|
+@opindex use @r{time, changing}
|
|
+Change the access time only.
|
|
+
|
|
+@item -c
|
|
+@itemx --no-create
|
|
+@opindex -c
|
|
+@opindex --no-create
|
|
+Do not create files that do not exist.
|
|
+
|
|
+@item -d
|
|
+@itemx --date=@var{time}
|
|
+@opindex -d
|
|
+@opindex --date
|
|
+@opindex time
|
|
+Use @var{time} instead of the current time. It can contain month names,
|
|
+time zones, @samp{am} and @samp{pm}, @samp{yesterday}, etc. For
|
|
+example, @option{--date="2004-02-27 14:19:13.489392193 +0530"}
|
|
+specifies the instant of time that is 489,392,193 nanoseconds after
|
|
+February 27, 2004 at 2:19:13 PM in a time zone that is 5 hours and 30
|
|
+minutes east of @acronym{UTC}. @xref{Date input formats}.
|
|
+File systems that do not support high-resolution time stamps
|
|
+silently ignore any excess precision here.
|
|
+
|
|
+@item -f
|
|
+@opindex -f
|
|
+@cindex BSD @command{touch} compatibility
|
|
+Ignored; for compatibility with BSD versions of @command{touch}.
|
|
+
|
|
+@item -m
|
|
+@itemx --time=mtime
|
|
+@itemx --time=modify
|
|
+@opindex -m
|
|
+@opindex --time
|
|
+@opindex mtime@r{, changing}
|
|
+@opindex modify @r{time, changing}
|
|
+Change the modification time only.
|
|
+
|
|
+@item -r @var{file}
|
|
+@itemx --reference=@var{file}
|
|
+@opindex -r
|
|
+@opindex --reference
|
|
+Use the times of the reference @var{file} instead of the current time.
|
|
+If this option is combined with the @option{--date=@var{time}}
|
|
+(@option{-d @var{time}}) option, the reference @var{file}'s time is
|
|
+the origin for any relative @var{time}s given, but is otherwise ignored.
|
|
+For example, @samp{-r foo -d '-5 seconds'} specifies a time stamp
|
|
+equal to five seconds before the corresponding time stamp for @file{foo}.
|
|
+
|
|
+@item -t [[@var{cc}]@var{yy}]@var{mmddhhmm}[.@var{ss}]
|
|
+Use the argument (optional four-digit or two-digit years, months,
|
|
+days, hours, minutes, optional seconds) instead of the current time.
|
|
+If the year is specified with only two digits, then @var{cc}
|
|
+is 20 for years in the range 0 @dots{} 68, and 19 for years in
|
|
+69 @dots{} 99. If no digits of the year are specified,
|
|
+the argument is interpreted as a date in the current year.
|
|
+Note that @var{ss} may be @samp{60}, to accommodate leap seconds.
|
|
+
|
|
+@end table
|
|
+
|
|
+@vindex _POSIX2_VERSION
|
|
+On older systems, @command{touch} supports an obsolete syntax, as follows.
|
|
+If no timestamp is given with any of the @option{-d}, @option{-r}, or
|
|
+@option{-t} options, and if there are two or more @var{file}s and the
|
|
+first @var{file} is of the form @samp{@var{mmddhhmm}[@var{yy}]} and this
|
|
+would be a valid argument to the @option{-t} option (if the @var{yy}, if
|
|
+any, were moved to the front), and if the represented year
|
|
+is in the range 1969--1999, that argument is interpreted as the time
|
|
+for the other files instead of as a file name.
|
|
+This obsolete behavior can be enabled or disabled with the
|
|
+@env{_POSIX2_VERSION} environment variable (@pxref{Standards
|
|
+conformance}), but portable scripts should avoid commands whose
|
|
+behavior depends on this variable.
|
|
+For example, use @samp{touch ./12312359 main.c} or @samp{touch -t
|
|
+12312359 main.c} rather than the ambiguous @samp{touch 12312359 main.c}.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node Disk usage
|
|
+@chapter Disk usage
|
|
+
|
|
+@cindex disk usage
|
|
+
|
|
+No disk can hold an infinite amount of data. These commands report
|
|
+how much disk storage is in use or available, report other file and
|
|
+file status information, and write buffers to disk.
|
|
+
|
|
+@menu
|
|
+* 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 memory and disk.
|
|
+* truncate invocation:: Shrink or extend the size of a file.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node df invocation
|
|
+@section @command{df}: Report file system disk space usage
|
|
+
|
|
+@pindex df
|
|
+@cindex file system disk usage
|
|
+@cindex disk usage by file system
|
|
+
|
|
+@command{df} reports the amount of disk space used and available on
|
|
+file systems. Synopsis:
|
|
+
|
|
+@example
|
|
+df [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+With no arguments, @command{df} reports the space used and available on all
|
|
+currently mounted file systems (of all types). Otherwise, @command{df}
|
|
+reports on the file system containing each argument @var{file}.
|
|
+
|
|
+Normally the disk space is printed in units of
|
|
+1024 bytes, but this can be overridden (@pxref{Block size}).
|
|
+Non-integer quantities are rounded up to the next higher unit.
|
|
+
|
|
+@cindex disk device file
|
|
+@cindex device file, disk
|
|
+If an argument @var{file} is a disk device file containing a mounted
|
|
+file system, @command{df} shows the space available on that file system
|
|
+rather than on the file system containing the device node (i.e., the root
|
|
+file system). @sc{gnu} @command{df} does not attempt to determine the disk usage
|
|
+on unmounted file systems, because on most kinds of systems doing so
|
|
+requires extremely nonportable intimate knowledge of file system
|
|
+structures.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -a
|
|
+@itemx --all
|
|
+@opindex -a
|
|
+@opindex --all
|
|
+@cindex automounter file systems
|
|
+@cindex ignore file systems
|
|
+Include in the listing dummy file systems, which
|
|
+are omitted by default. Such file systems are typically special-purpose
|
|
+pseudo-file-systems, such as automounter entries.
|
|
+
|
|
+@item -B @var{size}
|
|
+@itemx --block-size=@var{size}
|
|
+@opindex -B
|
|
+@opindex --block-size
|
|
+@cindex file system sizes
|
|
+Scale sizes by @var{size} before printing them (@pxref{Block size}).
|
|
+For example, @option{-BG} prints sizes in units of 1,073,741,824 bytes.
|
|
+
|
|
+@itemx --total
|
|
+@opindex --total
|
|
+@cindex grand total of disk size, usage and available space
|
|
+Print a grand total of all arguments after all arguments have
|
|
+been processed. This can be used to find out the total disk size, usage
|
|
+and available space of all listed devices.
|
|
+
|
|
+@optHumanReadable
|
|
+
|
|
+@item -H
|
|
+@opindex -H
|
|
+Equivalent to @option{--si}.
|
|
+
|
|
+@item -i
|
|
+@itemx --inodes
|
|
+@opindex -i
|
|
+@opindex --inodes
|
|
+@cindex inode usage
|
|
+List inode usage information instead of block usage. An inode (short
|
|
+for index node) contains information about a file such as its owner,
|
|
+permissions, timestamps, and location on the disk.
|
|
+
|
|
+@item -k
|
|
+@opindex -k
|
|
+@cindex kibibytes for file system sizes
|
|
+Print sizes in 1024-byte blocks, overriding the default block size
|
|
+(@pxref{Block size}).
|
|
+This option is equivalent to @option{--block-size=1K}.
|
|
+
|
|
+@item -l
|
|
+@itemx --local
|
|
+@opindex -l
|
|
+@opindex --local
|
|
+@cindex file system types, limiting output to certain
|
|
+Limit the listing to local file systems. By default, remote file systems
|
|
+are also listed.
|
|
+
|
|
+@item --no-sync
|
|
+@opindex --no-sync
|
|
+@cindex file system space, retrieving old data more quickly
|
|
+Do not invoke the @code{sync} system call before getting any usage data.
|
|
+This may make @command{df} run significantly faster on systems with many
|
|
+disks, but on some systems (notably SunOS) the results may be slightly
|
|
+out of date. This is the default.
|
|
+
|
|
+@item -P
|
|
+@itemx --portability
|
|
+@opindex -P
|
|
+@opindex --portability
|
|
+@cindex one-line output format
|
|
+@cindex @acronym{POSIX} output format
|
|
+@cindex portable output format
|
|
+@cindex output format, portable
|
|
+Use the @acronym{POSIX} output format. This is like the default format except
|
|
+for the following:
|
|
+
|
|
+@enumerate
|
|
+@item
|
|
+The information about each file system is always printed on exactly
|
|
+one line; a mount device is never put on a line by itself. This means
|
|
+that if the mount device name is more than 20 characters long (e.g., for
|
|
+some network mounts), the columns are misaligned.
|
|
+
|
|
+@item
|
|
+The labels in the header output line are changed to conform to @acronym{POSIX}.
|
|
+
|
|
+@item
|
|
+The default block size and output format are unaffected by the
|
|
+@env{DF_BLOCK_SIZE}, @env{BLOCK_SIZE} and @env{BLOCKSIZE} environment
|
|
+variables. However, the default block size is still affected by
|
|
+@env{POSIXLY_CORRECT}: it is 512 if @env{POSIXLY_CORRECT} is set, 1024
|
|
+otherwise. @xref{Block size}.
|
|
+@end enumerate
|
|
+
|
|
+@optSi
|
|
+
|
|
+@item --sync
|
|
+@opindex --sync
|
|
+@cindex file system space, retrieving current data more slowly
|
|
+Invoke the @code{sync} system call before getting any usage data. On
|
|
+some systems (notably SunOS), doing this yields more up to date results,
|
|
+but in general this option makes @command{df} much slower, especially when
|
|
+there are many or very busy file systems.
|
|
+
|
|
+@item -t @var{fstype}
|
|
+@itemx --type=@var{fstype}
|
|
+@opindex -t
|
|
+@opindex --type
|
|
+@cindex file system types, limiting output to certain
|
|
+Limit the listing to file systems of type @var{fstype}. Multiple
|
|
+file system types can be specified by giving multiple @option{-t} options.
|
|
+By default, nothing is omitted.
|
|
+
|
|
+@item -T
|
|
+@itemx --print-type
|
|
+@opindex -T
|
|
+@opindex --print-type
|
|
+@cindex file system types, printing
|
|
+Print each file system's type. The types printed here are the same ones
|
|
+you can include or exclude with @option{-t} and @option{-x}. The particular
|
|
+types printed are whatever is supported by the system. Here are some of
|
|
+the common names (this list is certainly not exhaustive):
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item nfs
|
|
+@cindex @acronym{NFS} file system type
|
|
+An @acronym{NFS} file system, i.e., one mounted over a network from another
|
|
+machine. This is the one type name which seems to be used uniformly by
|
|
+all systems.
|
|
+
|
|
+@item 4.2@r{, }ufs@r{, }efs@dots{}
|
|
+@cindex Linux file system types
|
|
+@cindex local file system types
|
|
+@opindex 4.2 @r{file system type}
|
|
+@opindex ufs @r{file system type}
|
|
+@opindex efs @r{file system type}
|
|
+A file system on a locally-mounted hard disk. (The system might even
|
|
+support more than one type here; Linux does.)
|
|
+
|
|
+@item hsfs@r{, }cdfs
|
|
+@cindex CD-ROM file system type
|
|
+@cindex High Sierra file system
|
|
+@opindex hsfs @r{file system type}
|
|
+@opindex cdfs @r{file system type}
|
|
+A file system on a CD-ROM drive. HP-UX uses @samp{cdfs}, most other
|
|
+systems use @samp{hsfs} (@samp{hs} for ``High Sierra'').
|
|
+
|
|
+@item pcfs
|
|
+@cindex PC file system
|
|
+@cindex DOS file system
|
|
+@cindex MS-DOS file system
|
|
+@cindex diskette file system
|
|
+@opindex pcfs
|
|
+An MS-DOS file system, usually on a diskette.
|
|
+
|
|
+@end table
|
|
+
|
|
+@item -x @var{fstype}
|
|
+@itemx --exclude-type=@var{fstype}
|
|
+@opindex -x
|
|
+@opindex --exclude-type
|
|
+Limit the listing to file systems not of type @var{fstype}.
|
|
+Multiple file system types can be eliminated by giving multiple
|
|
+@option{-x} options. By default, no file system types are omitted.
|
|
+
|
|
+@item -v
|
|
+Ignored; for compatibility with System V versions of @command{df}.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+Failure includes the case where no output is generated, so you can
|
|
+inspect the exit status of a command like @samp{df -t ext3 -t reiserfs
|
|
+@var{dir}} to test whether @var{dir} is on a file system of type
|
|
+@samp{ext3} or @samp{reiserfs}.
|
|
+
|
|
+
|
|
+@node du invocation
|
|
+@section @command{du}: Estimate file space usage
|
|
+
|
|
+@pindex du
|
|
+@cindex file space usage
|
|
+@cindex disk usage for files
|
|
+
|
|
+@command{du} reports the amount of disk space used by the specified files
|
|
+and for each subdirectory (of directory arguments). Synopsis:
|
|
+
|
|
+@example
|
|
+du [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+With no arguments, @command{du} reports the disk space for the current
|
|
+directory. Normally the disk space is printed in units of
|
|
+1024 bytes, but this can be overridden (@pxref{Block size}).
|
|
+Non-integer quantities are rounded up to the next higher unit.
|
|
+
|
|
+If two or more hard links point to the same file, only one of the hard
|
|
+links is counted. The @var{file} argument order affects which links
|
|
+are counted, and changing the argument order may change the numbers
|
|
+that @command{du} outputs.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -a
|
|
+@itemx --all
|
|
+@opindex -a
|
|
+@opindex --all
|
|
+Show counts for all files, not just directories.
|
|
+
|
|
+@itemx --apparent-size
|
|
+@opindex --apparent-size
|
|
+Print apparent sizes, rather than disk usage. The apparent size of a
|
|
+file is the number of bytes reported by @code{wc -c} on regular files,
|
|
+or more generally, @code{ls -l --block-size=1} or @code{stat --format=%s}.
|
|
+For example, a file containing the word @samp{zoo} with no newline would,
|
|
+of course, have an apparent size of 3. Such a small file may require
|
|
+anywhere from 0 to 16 KiB or more of disk space, depending on
|
|
+the type and configuration of the file system on which the file resides.
|
|
+However, a sparse file created with this command:
|
|
+
|
|
+@example
|
|
+dd bs=1 seek=2GiB if=/dev/null of=big
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+has an apparent size of 2 GiB, yet on most modern
|
|
+systems, it actually uses almost no disk space.
|
|
+
|
|
+@item -b
|
|
+@itemx --bytes
|
|
+@opindex -b
|
|
+@opindex --bytes
|
|
+Equivalent to @code{--apparent-size --block-size=1}.
|
|
+
|
|
+@item -B @var{size}
|
|
+@itemx --block-size=@var{size}
|
|
+@opindex -B
|
|
+@opindex --block-size
|
|
+@cindex file sizes
|
|
+Scale sizes by @var{size} before printing them (@pxref{Block size}).
|
|
+For example, @option{-BG} prints sizes in units of 1,073,741,824 bytes.
|
|
+
|
|
+@item -c
|
|
+@itemx --total
|
|
+@opindex -c
|
|
+@opindex --total
|
|
+@cindex grand total of disk space
|
|
+Print a grand total of all arguments after all arguments have
|
|
+been processed. This can be used to find out the total disk usage of
|
|
+a given set of files or directories.
|
|
+
|
|
+@item -D
|
|
+@itemx --dereference-args
|
|
+@opindex -D
|
|
+@opindex --dereference-args
|
|
+Dereference symbolic links that are command line arguments.
|
|
+Does not affect other symbolic links. This is helpful for finding
|
|
+out the disk usage of directories, such as @file{/usr/tmp}, which
|
|
+are often symbolic links.
|
|
+
|
|
+@c --files0-from=FILE
|
|
+@filesZeroFromOption{du,, with the @option{--total} (@option{-c}) option}
|
|
+
|
|
+@optHumanReadable
|
|
+
|
|
+@item -H
|
|
+@opindex -H
|
|
+Equivalent to @option{--dereference-args} (@option{-D}).
|
|
+
|
|
+@item -k
|
|
+@opindex -k
|
|
+@cindex kibibytes for file sizes
|
|
+Print sizes in 1024-byte blocks, overriding the default block size
|
|
+(@pxref{Block size}).
|
|
+This option is equivalent to @option{--block-size=1K}.
|
|
+
|
|
+@item -l
|
|
+@itemx --count-links
|
|
+@opindex -l
|
|
+@opindex --count-links
|
|
+@cindex hard links, counting in @command{du}
|
|
+Count the size of all files, even if they have appeared already (as a
|
|
+hard link).
|
|
+
|
|
+@item -L
|
|
+@itemx --dereference
|
|
+@opindex -L
|
|
+@opindex --dereference
|
|
+@cindex symbolic links, dereferencing in @command{du}
|
|
+Dereference symbolic links (show the disk space used by the file
|
|
+or directory that the link points to instead of the space used by
|
|
+the link).
|
|
+
|
|
+@item -m
|
|
+@opindex -m
|
|
+@cindex mebibytes for file sizes
|
|
+Print sizes in 1,048,576-byte blocks, overriding the default block size
|
|
+(@pxref{Block size}).
|
|
+This option is equivalent to @option{--block-size=1M}.
|
|
+
|
|
+@item -P
|
|
+@itemx --no-dereference
|
|
+@opindex -P
|
|
+@opindex --no-dereference
|
|
+@cindex symbolic links, dereferencing in @command{du}
|
|
+For each symbolic links encountered by @command{du},
|
|
+consider the disk space used by the symbolic link.
|
|
+
|
|
+@item --max-depth=@var{depth}
|
|
+@opindex --max-depth=@var{depth}
|
|
+@cindex limiting output of @command{du}
|
|
+Show the total for each directory (and file if --all) that is at
|
|
+most MAX_DEPTH levels down from the root of the hierarchy. The root
|
|
+is at level 0, so @code{du --max-depth=0} is equivalent to @code{du -s}.
|
|
+
|
|
+@item -0
|
|
+@opindex -0
|
|
+@itemx --null
|
|
+@opindex --null
|
|
+@cindex output null-byte-terminated lines
|
|
+Output a zero byte (@acronym{ASCII} @sc{nul}) at the end of each line,
|
|
+rather than a newline. This option enables other programs to parse the
|
|
+output of @command{du} even when that output would contain file names
|
|
+with embedded newlines.
|
|
+
|
|
+@optSi
|
|
+
|
|
+@item -s
|
|
+@itemx --summarize
|
|
+@opindex -s
|
|
+@opindex --summarize
|
|
+Display only a total for each argument.
|
|
+
|
|
+@item -S
|
|
+@itemx --separate-dirs
|
|
+@opindex -S
|
|
+@opindex --separate-dirs
|
|
+Normally, in the output of @command{du} (when not using @option{--summarize}),
|
|
+the size listed next to a directory name, @var{d}, represents the sum
|
|
+of sizes of all entries beneath @var{d} as well as the size of @var{d} itself.
|
|
+With @option{--separate-dirs}, the size reported for a directory name,
|
|
+@var{d}, is merely the @code{stat.st_size}-derived size of the directory
|
|
+entry, @var{d}.
|
|
+
|
|
+@itemx --time
|
|
+@opindex --time
|
|
+@cindex last modified dates, displaying in @command{du}
|
|
+Show time of the most recent modification of any file in the directory,
|
|
+or any of its subdirectories.
|
|
+
|
|
+@itemx --time=ctime
|
|
+@itemx --time=status
|
|
+@itemx --time=use
|
|
+@opindex --time
|
|
+@opindex ctime@r{, show the most recent}
|
|
+@opindex status time@r{, show the most recent}
|
|
+@opindex use time@r{, show the most recent}
|
|
+Show the most recent status change time (the @samp{ctime} in the inode) of
|
|
+any file in the directory, instead of the modification time.
|
|
+
|
|
+@itemx --time=atime
|
|
+@itemx --time=access
|
|
+@opindex --time
|
|
+@opindex atime@r{, show the most recent}
|
|
+@opindex access time@r{, show the most recent}
|
|
+Show the most recent access time (the @samp{atime} in the inode) of
|
|
+any file in the directory, instead of the modification time.
|
|
+
|
|
+@item --time-style=@var{style}
|
|
+@opindex --time-style
|
|
+@cindex time style
|
|
+List timestamps in style @var{style}. This option has an effect only if
|
|
+the @option{--time} option is also specified. The @var{style} should
|
|
+be one of the following:
|
|
+
|
|
+@table @samp
|
|
+@item +@var{format}
|
|
+@vindex LC_TIME
|
|
+List timestamps using @var{format}, where @var{format} is interpreted
|
|
+like the format argument of @command{date} (@pxref{date invocation}).
|
|
+For example, @option{--time-style="+%Y-%m-%d %H:%M:%S"} causes
|
|
+@command{du} to list timestamps like @samp{2002-03-30 23:45:56}. As
|
|
+with @command{date}, @var{format}'s interpretation is affected by the
|
|
+@env{LC_TIME} locale category.
|
|
+
|
|
+@item full-iso
|
|
+List timestamps in full using @acronym{ISO} 8601 date, time, and time zone
|
|
+format with nanosecond precision, e.g., @samp{2002-03-30
|
|
+23:45:56.477817180 -0700}. This style is equivalent to
|
|
+@samp{+%Y-%m-%d %H:%M:%S.%N %z}.
|
|
+
|
|
+@item long-iso
|
|
+List @acronym{ISO} 8601 date and time in minutes, e.g.,
|
|
+@samp{2002-03-30 23:45}. These timestamps are shorter than
|
|
+@samp{full-iso} timestamps, and are usually good enough for everyday
|
|
+work. This style is equivalent to @samp{+%Y-%m-%d %H:%M}.
|
|
+
|
|
+@item iso
|
|
+List @acronym{ISO} 8601 dates for timestamps, e.g., @samp{2002-03-30}.
|
|
+This style is equivalent to @samp{+%Y-%m-%d}.
|
|
+@end table
|
|
+
|
|
+@vindex TIME_STYLE
|
|
+You can specify the default value of the @option{--time-style} option
|
|
+with the environment variable @env{TIME_STYLE}; if @env{TIME_STYLE} is not set
|
|
+the default style is @samp{long-iso}. For compatibility with @command{ls},
|
|
+if @env{TIME_STYLE} begins with @samp{+} and contains a newline,
|
|
+the newline and any later characters are ignored; if @env{TIME_STYLE}
|
|
+begins with @samp{posix-} the @samp{posix-} is ignored; and if
|
|
+@env{TIME_STYLE} is @samp{locale} it is ignored.
|
|
+
|
|
+@item -x
|
|
+@itemx --one-file-system
|
|
+@opindex -x
|
|
+@opindex --one-file-system
|
|
+@cindex one file system, restricting @command{du} to
|
|
+Skip directories that are on different file systems from the one that
|
|
+the argument being processed is on.
|
|
+
|
|
+@item --exclude=@var{pattern}
|
|
+@opindex --exclude=@var{pattern}
|
|
+@cindex excluding files from @command{du}
|
|
+When recursing, skip subdirectories or files matching @var{pattern}.
|
|
+For example, @code{du --exclude='*.o'} excludes files whose names
|
|
+end in @samp{.o}.
|
|
+
|
|
+@item -X @var{file}
|
|
+@itemx --exclude-from=@var{file}
|
|
+@opindex -X @var{file}
|
|
+@opindex --exclude-from=@var{file}
|
|
+@cindex excluding files from @command{du}
|
|
+Like @option{--exclude}, except take the patterns to exclude from @var{file},
|
|
+one per line. If @var{file} is @samp{-}, take the patterns from standard
|
|
+input.
|
|
+
|
|
+@end table
|
|
+
|
|
+@cindex NFS mounts from BSD to HP-UX
|
|
+On BSD systems, @command{du} reports sizes that are half the correct
|
|
+values for files that are NFS-mounted from HP-UX systems. On HP-UX
|
|
+systems, it reports sizes that are twice the correct values for
|
|
+files that are NFS-mounted from BSD systems. This is due to a flaw
|
|
+in HP-UX; it also affects the HP-UX @command{du} program.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node stat invocation
|
|
+@section @command{stat}: Report file or file system status
|
|
+
|
|
+@pindex stat
|
|
+@cindex file status
|
|
+@cindex file system status
|
|
+
|
|
+@command{stat} displays information about the specified file(s). Synopsis:
|
|
+
|
|
+@example
|
|
+stat [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+With no option, @command{stat} reports all information about the given files.
|
|
+But it also can be used to report the information of the file systems the
|
|
+given files are located on. If the files are links, @command{stat} can
|
|
+also give information about the files the links point to.
|
|
+
|
|
+@mayConflictWithShellBuiltIn{stat}
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -L
|
|
+@itemx --dereference
|
|
+@opindex -L
|
|
+@opindex --dereference
|
|
+@cindex symbolic links, dereferencing in @command{stat}
|
|
+Change how @command{stat} treats symbolic links.
|
|
+With this option, @command{stat} acts on the file referenced
|
|
+by each symbolic link argument.
|
|
+Without it, @command{stat} acts on any symbolic link argument directly.
|
|
+
|
|
+@item -f
|
|
+@itemx --file-system
|
|
+@opindex -f
|
|
+@opindex --file-system
|
|
+@cindex file systems
|
|
+Report information about the file systems where the given files are located
|
|
+instead of information about the files themselves.
|
|
+
|
|
+@item -c
|
|
+@itemx --format=@var{format}
|
|
+@opindex -c
|
|
+@opindex --format=@var{format}
|
|
+@cindex output format
|
|
+Use @var{format} rather than the default format.
|
|
+@var{format} is automatically newline-terminated, so
|
|
+running a command like the following with two or more @var{file}
|
|
+operands produces a line of output for each operand:
|
|
+@example
|
|
+$ stat --format=%d:%i / /usr
|
|
+2050:2
|
|
+2057:2
|
|
+@end example
|
|
+
|
|
+@itemx --printf=@var{format}
|
|
+@opindex --printf=@var{format}
|
|
+@cindex output format
|
|
+Use @var{format} rather than the default format.
|
|
+Like @option{--format}, but interpret backslash escapes,
|
|
+and do not output a mandatory trailing newline.
|
|
+If you want a newline, include @samp{\n} in the @var{format}.
|
|
+Here's how you would use @option{--printf} to print the device
|
|
+and inode numbers of @file{/} and @file{/usr}:
|
|
+@example
|
|
+$ stat --printf='%d:%i\n' / /usr
|
|
+2050:2
|
|
+2057:2
|
|
+@end example
|
|
+
|
|
+@item -t
|
|
+@itemx --terse
|
|
+@opindex -t
|
|
+@opindex --terse
|
|
+@cindex terse output
|
|
+Print the information in terse form, suitable for parsing by other programs.
|
|
+
|
|
+@end table
|
|
+
|
|
+The valid @var{format} directives for files with @option{--format} and
|
|
+@option{--printf} are:
|
|
+
|
|
+@itemize @bullet
|
|
+@item %a - Access rights in octal
|
|
+@item %A - Access rights in human readable form
|
|
+@item %b - Number of blocks allocated (see @samp{%B})
|
|
+@item %B - The size in bytes of each block reported by @samp{%b}
|
|
+@item %d - Device number in decimal
|
|
+@item %D - Device number in hex
|
|
+@item %f - Raw mode in hex
|
|
+@item %F - File type
|
|
+@item %g - Group ID of owner
|
|
+@item %G - Group name of owner
|
|
+@item %h - Number of hard links
|
|
+@item %i - Inode number
|
|
+@item %n - File name
|
|
+@item %N - Quoted file name with dereference if symbolic link
|
|
+@item %o - I/O block size
|
|
+@item %s - Total size, in bytes
|
|
+@item %t - Major device type in hex
|
|
+@item %T - Minor device type in hex
|
|
+@item %u - User ID of owner
|
|
+@item %U - User name of owner
|
|
+@item %x - Time of last access
|
|
+@item %X - Time of last access as seconds since Epoch
|
|
+@item %y - Time of last modification
|
|
+@item %Y - Time of last modification as seconds since Epoch
|
|
+@item %z - Time of last change
|
|
+@item %Z - Time of last change as seconds since Epoch
|
|
+@end itemize
|
|
+
|
|
+When listing file system information (@option{--file-system} (@option{-f})),
|
|
+you must use a different set of @var{format} directives:
|
|
+
|
|
+@itemize @bullet
|
|
+@item %a - Free blocks available to non-super-user
|
|
+@item %b - Total data blocks in file system
|
|
+@item %c - Total file nodes in file system
|
|
+@item %d - Free file nodes in file system
|
|
+@item %f - Free blocks in file system
|
|
+@item %i - File System ID in hex
|
|
+@item %l - Maximum length of file names
|
|
+@item %n - File name
|
|
+@item %s - Block size (for faster transfers)
|
|
+@item %S - Fundamental block size (for block counts)
|
|
+@item %t - Type in hex
|
|
+@item %T - Type in human readable form
|
|
+@end itemize
|
|
+
|
|
+@vindex TZ
|
|
+Time stamps are listed according to the time zone rules specified by
|
|
+the @env{TZ} environment variable, or by the system default rules if
|
|
+@env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone
|
|
+with @env{TZ}, libc, The GNU C Library Reference Manual}.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node sync invocation
|
|
+@section @command{sync}: Synchronize data on disk with memory
|
|
+
|
|
+@pindex sync
|
|
+@cindex synchronize disk and memory
|
|
+
|
|
+@cindex superblock, writing
|
|
+@cindex inodes, written buffered
|
|
+@command{sync} writes any data buffered in memory out to disk. This can
|
|
+include (but is not limited to) modified superblocks, modified inodes,
|
|
+and delayed reads and writes. This must be implemented by the kernel;
|
|
+The @command{sync} program does nothing but exercise the @code{sync} system
|
|
+call.
|
|
+
|
|
+@cindex crashes and corruption
|
|
+The kernel keeps data in memory to avoid doing (relatively slow) disk
|
|
+reads and writes. This improves performance, but if the computer
|
|
+crashes, data may be lost or the file system corrupted as a
|
|
+result. The @command{sync} command ensures everything in memory
|
|
+is written to disk.
|
|
+
|
|
+Any arguments are ignored, except for a lone @option{--help} or
|
|
+@option{--version} (@pxref{Common options}).
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node truncate invocation
|
|
+@section @command{truncate}: Shrink or extend the size of a file
|
|
+
|
|
+@pindex truncate
|
|
+@cindex truncating, file sizes
|
|
+
|
|
+@command{truncate} shrinks or extends the size of each @var{file} to the
|
|
+specified size. Synopsis:
|
|
+
|
|
+@example
|
|
+truncate @var{option}@dots{} @var{file}@dots{}
|
|
+@end example
|
|
+
|
|
+@cindex files, creating
|
|
+Any @var{file} that does not exist is created.
|
|
+
|
|
+@cindex sparse files, creating
|
|
+@cindex holes, creating files with
|
|
+If a @var{file} is larger than the specified size, the extra data is lost.
|
|
+If a @var{file} is shorter, it is extended and the extended part (or hole)
|
|
+reads as zero bytes.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -c
|
|
+@itemx --no-create
|
|
+@opindex -c
|
|
+@opindex --no-create
|
|
+Do not create files that do not exist.
|
|
+
|
|
+@item -o
|
|
+@itemx --io-blocks
|
|
+@opindex -o
|
|
+@opindex --io-blocks
|
|
+Treat @var{size} as number of I/O blocks of the @var{file} rather than bytes.
|
|
+
|
|
+@item -r @var{rfile}
|
|
+@itemx --reference=@var{rfile}
|
|
+@opindex -r
|
|
+@opindex --reference
|
|
+Set the size of each @var{file} to the same size as @var{rfile}.
|
|
+
|
|
+@item -s @var{size}
|
|
+@itemx --size=@var{size}
|
|
+@opindex -s
|
|
+@opindex --size
|
|
+Set the size of each @var{file} to this @var{size}.
|
|
+@multiplierSuffixesNoBlocks{size}
|
|
+
|
|
+@var{size} may also be prefixed by one of the following to adjust
|
|
+the size of each @var{file} based on their current size:
|
|
+@example
|
|
+@samp{+} => extend by
|
|
+@samp{-} => reduce by
|
|
+@samp{<} => at most
|
|
+@samp{>} => at least
|
|
+@samp{/} => round down to multiple of
|
|
+@samp{%} => round up to multiple of
|
|
+@end example
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node Printing text
|
|
+@chapter Printing text
|
|
+
|
|
+@cindex printing text, commands for
|
|
+@cindex commands for printing text
|
|
+
|
|
+This section describes commands that display text strings.
|
|
+
|
|
+@menu
|
|
+* echo invocation:: Print a line of text.
|
|
+* printf invocation:: Format and print data.
|
|
+* yes invocation:: Print a string until interrupted.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node echo invocation
|
|
+@section @command{echo}: Print a line of text
|
|
+
|
|
+@pindex echo
|
|
+@cindex displaying text
|
|
+@cindex printing text
|
|
+@cindex text, displaying
|
|
+@cindex arbitrary text, displaying
|
|
+
|
|
+@command{echo} writes each given @var{string} to standard output, with a
|
|
+space between each and a newline after the last one. Synopsis:
|
|
+
|
|
+@example
|
|
+echo [@var{option}]@dots{} [@var{string}]@dots{}
|
|
+@end example
|
|
+
|
|
+@mayConflictWithShellBuiltIn{echo}
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+Options must precede operands, and the normally-special argument
|
|
+@samp{--} has no special meaning and is treated like any other
|
|
+@var{string}.
|
|
+
|
|
+@table @samp
|
|
+@item -n
|
|
+@opindex -n
|
|
+Do not output the trailing newline.
|
|
+
|
|
+@item -e
|
|
+@opindex -e
|
|
+@cindex backslash escapes
|
|
+Enable interpretation of the following backslash-escaped characters in
|
|
+each @var{string}:
|
|
+
|
|
+@table @samp
|
|
+@item \a
|
|
+alert (bell)
|
|
+@item \b
|
|
+backspace
|
|
+@item \c
|
|
+produce no further output
|
|
+@item \f
|
|
+form feed
|
|
+@item \n
|
|
+newline
|
|
+@item \r
|
|
+carriage return
|
|
+@item \t
|
|
+horizontal tab
|
|
+@item \v
|
|
+vertical tab
|
|
+@item \\
|
|
+backslash
|
|
+@item \0@var{nnn}
|
|
+the eight-bit value that is the octal number @var{nnn}
|
|
+(zero to three octal digits)
|
|
+@item \@var{nnn}
|
|
+the eight-bit value that is the octal number @var{nnn}
|
|
+(one to three octal digits)
|
|
+@item \x@var{hh}
|
|
+the eight-bit value that is the hexadecimal number @var{hh}
|
|
+(one or two hexadecimal digits)
|
|
+@end table
|
|
+
|
|
+@item -E
|
|
+@opindex -E
|
|
+@cindex backslash escapes
|
|
+Disable interpretation of backslash escapes in each @var{string}.
|
|
+This is the default. If @option{-e} and @option{-E} are both
|
|
+specified, the last one given takes effect.
|
|
+
|
|
+@end table
|
|
+
|
|
+@vindex POSIXLY_CORRECT
|
|
+If the @env{POSIXLY_CORRECT} environment variable is set, then when
|
|
+@command{echo}'s first argument is not @option{-n} it outputs
|
|
+option-like arguments instead of treating them as options. For
|
|
+example, @code{echo -ne hello} outputs @samp{-ne hello} instead of
|
|
+plain @samp{hello}.
|
|
+
|
|
+@acronym{POSIX} does not require support for any options, and says
|
|
+that the behavior of @command{echo} is implementation-defined if any
|
|
+@var{string} contains a backslash or if the first argument is
|
|
+@option{-n}. Portable programs can use the @command{printf} command
|
|
+if they need to omit trailing newlines or output control characters or
|
|
+backslashes. @xref{printf invocation}.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node printf invocation
|
|
+@section @command{printf}: Format and print data
|
|
+
|
|
+@pindex printf
|
|
+@command{printf} does formatted printing of text. Synopsis:
|
|
+
|
|
+@example
|
|
+printf @var{format} [@var{argument}]@dots{}
|
|
+@end example
|
|
+
|
|
+@command{printf} prints the @var{format} string, interpreting @samp{%}
|
|
+directives and @samp{\} escapes to format numeric and string arguments
|
|
+in a way that is mostly similar to the C @samp{printf} function.
|
|
+@xref{Output Conversion Syntax,, @command{printf} format directives,
|
|
+libc, The GNU C Library Reference Manual}, for details.
|
|
+The differences are listed below.
|
|
+
|
|
+@mayConflictWithShellBuiltIn{printf}
|
|
+
|
|
+@itemize @bullet
|
|
+
|
|
+@item
|
|
+The @var{format} argument is reused as necessary to convert all the
|
|
+given @var{argument}s. For example, the command @samp{printf %s a b}
|
|
+outputs @samp{ab}.
|
|
+
|
|
+@item
|
|
+Missing @var{argument}s are treated as null strings or as zeros,
|
|
+depending on whether the context expects a string or a number. For
|
|
+example, the command @samp{printf %sx%d} prints @samp{x0}.
|
|
+
|
|
+@item
|
|
+@kindex \c
|
|
+An additional escape, @samp{\c}, causes @command{printf} to produce no
|
|
+further output. For example, the command @samp{printf 'A%sC\cD%sF' B
|
|
+E} prints @samp{ABC}.
|
|
+
|
|
+@item
|
|
+The hexadecimal escape sequence @samp{\x@var{hh}} has at most two
|
|
+digits, as opposed to C where it can have an unlimited number of
|
|
+digits. For example, the command @samp{printf '\x07e'} prints two
|
|
+bytes, whereas the C statement @samp{printf ("\x07e")} prints just
|
|
+one.
|
|
+
|
|
+@item
|
|
+@kindex %b
|
|
+@command{printf} has an additional directive, @samp{%b}, which prints its
|
|
+argument string with @samp{\} escapes interpreted in the same way as in
|
|
+the @var{format} string, except that octal escapes are of the form
|
|
+@samp{\0@var{ooo}} where @var{ooo} is 0 to 3 octal digits.
|
|
+If a precision is also given, it limits the number of bytes printed
|
|
+from the converted string.
|
|
+
|
|
+@item
|
|
+Numeric arguments must be single C constants, possibly with leading
|
|
+@samp{+} or @samp{-}. For example, @samp{printf %.4d -3} outputs
|
|
+@samp{-0003}.
|
|
+
|
|
+@item
|
|
+@vindex POSIXLY_CORRECT
|
|
+If the leading character of a numeric argument is @samp{"} or @samp{'}
|
|
+then its value is the numeric value of the immediately following
|
|
+character. Any remaining characters are silently ignored if the
|
|
+@env{POSIXLY_CORRECT} environment variable is set; otherwise, a
|
|
+warning is printed. For example, @samp{printf "%d" "'a"} outputs
|
|
+@samp{97} on hosts that use the @acronym{ASCII} character set, since
|
|
+@samp{a} has the numeric value 97 in @acronym{ASCII}.
|
|
+
|
|
+@end itemize
|
|
+
|
|
+@vindex LC_NUMERIC
|
|
+A floating-point argument must use a period before any fractional
|
|
+digits, but is printed according to the @env{LC_NUMERIC} category of the
|
|
+current locale. For example, in a locale whose radix character is a
|
|
+comma, the command @samp{printf %g 3.14} outputs @samp{3,14} whereas
|
|
+the command @samp{printf %g 3,14} is an error.
|
|
+
|
|
+@kindex \@var{ooo}
|
|
+@kindex \x@var{hh}
|
|
+@command{printf} interprets @samp{\@var{ooo}} in @var{format} as an octal number
|
|
+(if @var{ooo} is 1 to 3 octal digits) specifying a character to print,
|
|
+and @samp{\x@var{hh}} as a hexadecimal number (if @var{hh} is 1 to 2 hex
|
|
+digits) specifying a character to print.
|
|
+
|
|
+@kindex \uhhhh
|
|
+@kindex \Uhhhhhhhh
|
|
+@cindex Unicode
|
|
+@cindex ISO/IEC 10646
|
|
+@vindex LC_CTYPE
|
|
+@command{printf} interprets two character syntaxes introduced in
|
|
+@acronym{ISO} C 99:
|
|
+@samp{\u} for 16-bit Unicode (@acronym{ISO}/@acronym{IEC} 10646)
|
|
+characters, specified as
|
|
+four hexadecimal digits @var{hhhh}, and @samp{\U} for 32-bit Unicode
|
|
+characters, specified as eight hexadecimal digits @var{hhhhhhhh}.
|
|
+@command{printf} outputs the Unicode characters
|
|
+according to the @env{LC_CTYPE} locale. Unicode characters in the ranges
|
|
+U+0000...U+009F, U+D800...U+DFFF cannot be specified by this syntax, except
|
|
+for U+0024 ($), U+0040 (@@), and U+0060 (@`).
|
|
+
|
|
+The processing of @samp{\u} and @samp{\U} requires a full-featured
|
|
+@code{iconv} facility. It is activated on systems with glibc 2.2 (or newer),
|
|
+or when @code{libiconv} is installed prior to this package. Otherwise
|
|
+@samp{\u} and @samp{\U} will print as-is.
|
|
+
|
|
+The only options are a lone @option{--help} or
|
|
+@option{--version}. @xref{Common options}.
|
|
+Options must precede operands.
|
|
+
|
|
+The Unicode character syntaxes are useful for writing strings in a locale
|
|
+independent way. For example, a string containing the Euro currency symbol
|
|
+
|
|
+@example
|
|
+$ env printf '\u20AC 14.95'
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+will be output correctly in all locales supporting the Euro symbol
|
|
+(@acronym{ISO}-8859-15, UTF-8, and others). Similarly, a Chinese string
|
|
+
|
|
+@example
|
|
+$ env printf '\u4e2d\u6587'
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+will be output correctly in all Chinese locales (GB2312, BIG5, UTF-8, etc).
|
|
+
|
|
+Note that in these examples, the @command{printf} command has been
|
|
+invoked via @command{env} to ensure that we run the program found via
|
|
+your shell's search path, and not a shell alias or a built-in function.
|
|
+
|
|
+For larger strings, you don't need to look up the hexadecimal code
|
|
+values of each character one by one. @acronym{ASCII} characters mixed with \u
|
|
+escape sequences is also known as the JAVA source file encoding. You can
|
|
+use GNU recode 3.5c (or newer) to convert strings to this encoding. Here
|
|
+is how to convert a piece of text into a shell script which will output
|
|
+this text in a locale-independent way:
|
|
+
|
|
+@smallexample
|
|
+$ LC_CTYPE=zh_CN.big5 /usr/local/bin/printf \
|
|
+ '\u4e2d\u6587\n' > sample.txt
|
|
+$ recode BIG5..JAVA < sample.txt \
|
|
+ | sed -e "s|^|/usr/local/bin/printf '|" -e "s|$|\\\\n'|" \
|
|
+ > sample.sh
|
|
+@end smallexample
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node yes invocation
|
|
+@section @command{yes}: Print a string until interrupted
|
|
+
|
|
+@pindex yes
|
|
+@cindex repeated output of a string
|
|
+
|
|
+@command{yes} prints the command line arguments, separated by spaces and
|
|
+followed by a newline, forever until it is killed. If no arguments are
|
|
+given, it prints @samp{y} followed by a newline forever until killed.
|
|
+
|
|
+Upon a write error, @command{yes} exits with status @samp{1}.
|
|
+
|
|
+The only options are a lone @option{--help} or @option{--version}.
|
|
+To output an argument that begins with
|
|
+@samp{-}, precede it with @option{--}, e.g., @samp{yes -- --help}.
|
|
+@xref{Common options}.
|
|
+
|
|
+
|
|
+@node Conditions
|
|
+@chapter Conditions
|
|
+
|
|
+@cindex conditions
|
|
+@cindex commands for exit status
|
|
+@cindex exit status commands
|
|
+
|
|
+This section describes commands that are primarily useful for their exit
|
|
+status, rather than their output. Thus, they are often used as the
|
|
+condition of shell @code{if} statements, or as the last command in a
|
|
+pipeline.
|
|
+
|
|
+@menu
|
|
+* false invocation:: Do nothing, unsuccessfully.
|
|
+* true invocation:: Do nothing, successfully.
|
|
+* test invocation:: Check file types and compare values.
|
|
+* expr invocation:: Evaluate expressions.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node false invocation
|
|
+@section @command{false}: Do nothing, unsuccessfully
|
|
+
|
|
+@pindex false
|
|
+@cindex do nothing, unsuccessfully
|
|
+@cindex failure exit status
|
|
+@cindex exit status of @command{false}
|
|
+
|
|
+@command{false} does nothing except return an exit status of 1, meaning
|
|
+@dfn{failure}. It can be used as a place holder in shell scripts
|
|
+where an unsuccessful command is needed.
|
|
+In most modern shells, @command{false} is a built-in command, so when
|
|
+you use @samp{false} in a script, you're probably using the built-in
|
|
+command, not the one documented here.
|
|
+
|
|
+@command{false} honors the @option{--help} and @option{--version} options.
|
|
+
|
|
+This version of @command{false} is implemented as a C program, and is thus
|
|
+more secure and faster than a shell script implementation, and may safely
|
|
+be used as a dummy shell for the purpose of disabling accounts.
|
|
+
|
|
+Note that @command{false} (unlike all other programs documented herein)
|
|
+exits unsuccessfully, even when invoked with
|
|
+@option{--help} or @option{--version}.
|
|
+
|
|
+Portable programs should not assume that the exit status of
|
|
+@command{false} is 1, as it is greater than 1 on some
|
|
+non-@acronym{GNU} hosts.
|
|
+
|
|
+
|
|
+@node true invocation
|
|
+@section @command{true}: Do nothing, successfully
|
|
+
|
|
+@pindex true
|
|
+@cindex do nothing, successfully
|
|
+@cindex no-op
|
|
+@cindex successful exit
|
|
+@cindex exit status of @command{true}
|
|
+
|
|
+@command{true} does nothing except return an exit status of 0, meaning
|
|
+@dfn{success}. It can be used as a place holder in shell scripts
|
|
+where a successful command is needed, although the shell built-in
|
|
+command @code{:} (colon) may do the same thing faster.
|
|
+In most modern shells, @command{true} is a built-in command, so when
|
|
+you use @samp{true} in a script, you're probably using the built-in
|
|
+command, not the one documented here.
|
|
+
|
|
+@command{true} honors the @option{--help} and @option{--version} options.
|
|
+
|
|
+Note, however, that it is possible to cause @command{true}
|
|
+to exit with nonzero status: with the @option{--help} or @option{--version}
|
|
+option, and with standard
|
|
+output already closed or redirected to a file that evokes an I/O error.
|
|
+For example, using a Bourne-compatible shell:
|
|
+
|
|
+@example
|
|
+$ ./true --version >&-
|
|
+./true: write error: Bad file number
|
|
+$ ./true --version > /dev/full
|
|
+./true: write error: No space left on device
|
|
+@end example
|
|
+
|
|
+This version of @command{true} is implemented as a C program, and is thus
|
|
+more secure and faster than a shell script implementation, and may safely
|
|
+be used as a dummy shell for the purpose of disabling accounts.
|
|
+
|
|
+@node test invocation
|
|
+@section @command{test}: Check file types and compare values
|
|
+
|
|
+@pindex test
|
|
+@cindex check file types
|
|
+@cindex compare values
|
|
+@cindex expression evaluation
|
|
+
|
|
+@command{test} returns a status of 0 (true) or 1 (false) depending on the
|
|
+evaluation of the conditional expression @var{expr}. Each part of the
|
|
+expression must be a separate argument.
|
|
+
|
|
+@command{test} has file status checks, string operators, and numeric
|
|
+comparison operators.
|
|
+
|
|
+@command{test} has an alternate form that uses opening and closing
|
|
+square brackets instead a leading @samp{test}. For example, instead
|
|
+of @samp{test -d /}, you can write @samp{[ -d / ]}. The square
|
|
+brackets must be separate arguments; for example, @samp{[-d /]} does
|
|
+not have the desired effect. Since @samp{test @var{expr}} and @samp{[
|
|
+@var{expr} ]} have the same meaning, only the former form is discussed
|
|
+below.
|
|
+
|
|
+Synopses:
|
|
+
|
|
+@example
|
|
+test @var{expression}
|
|
+test
|
|
+[ @var{expression} ]
|
|
+[ ]
|
|
+[ @var{option}
|
|
+@end example
|
|
+
|
|
+@mayConflictWithShellBuiltIn{test}
|
|
+
|
|
+If @var{expression} is omitted, @command{test} returns false.
|
|
+If @var{expression} is a single argument,
|
|
+@command{test} returns false if the argument is null and true otherwise. The argument
|
|
+can be any string, including strings like @samp{-d}, @samp{-1},
|
|
+@samp{--}, @samp{--help}, and @samp{--version} that most other
|
|
+programs would treat as options. To get help and version information,
|
|
+invoke the commands @samp{[ --help} and @samp{[ --version}, without
|
|
+the usual closing brackets. @xref{Common options}.
|
|
+
|
|
+@cindex exit status of @command{test}
|
|
+Exit status:
|
|
+
|
|
+@display
|
|
+0 if the expression is true,
|
|
+1 if the expression is false,
|
|
+2 if an error occurred.
|
|
+@end display
|
|
+
|
|
+@menu
|
|
+* File type tests:: -[bcdfhLpSt]
|
|
+* Access permission tests:: -[gkruwxOG]
|
|
+* File characteristic tests:: -e -s -nt -ot -ef
|
|
+* String tests:: -z -n = !=
|
|
+* Numeric tests:: -eq -ne -lt -le -gt -ge
|
|
+* Connectives for test:: ! -a -o
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node File type tests
|
|
+@subsection File type tests
|
|
+
|
|
+@cindex file type tests
|
|
+
|
|
+These options test for particular types of files. (Everything's a file,
|
|
+but not all files are the same!)
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -b @var{file}
|
|
+@opindex -b
|
|
+@cindex block special check
|
|
+True if @var{file} exists and is a block special device.
|
|
+
|
|
+@item -c @var{file}
|
|
+@opindex -c
|
|
+@cindex character special check
|
|
+True if @var{file} exists and is a character special device.
|
|
+
|
|
+@item -d @var{file}
|
|
+@opindex -d
|
|
+@cindex directory check
|
|
+True if @var{file} exists and is a directory.
|
|
+
|
|
+@item -f @var{file}
|
|
+@opindex -f
|
|
+@cindex regular file check
|
|
+True if @var{file} exists and is a regular file.
|
|
+
|
|
+@item -h @var{file}
|
|
+@itemx -L @var{file}
|
|
+@opindex -L
|
|
+@opindex -h
|
|
+@cindex symbolic link check
|
|
+True if @var{file} exists and is a symbolic link.
|
|
+Unlike all other file-related tests, this test does not dereference
|
|
+@var{file} if it is a symbolic link.
|
|
+
|
|
+@item -p @var{file}
|
|
+@opindex -p
|
|
+@cindex named pipe check
|
|
+True if @var{file} exists and is a named pipe.
|
|
+
|
|
+@item -S @var{file}
|
|
+@opindex -S
|
|
+@cindex socket check
|
|
+True if @var{file} exists and is a socket.
|
|
+
|
|
+@item -t @var{fd}
|
|
+@opindex -t
|
|
+@cindex terminal check
|
|
+True if @var{fd} is a file descriptor that is associated with a
|
|
+terminal.
|
|
+
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Access permission tests
|
|
+@subsection Access permission tests
|
|
+
|
|
+@cindex access permission tests
|
|
+@cindex permission tests
|
|
+
|
|
+These options test for particular access permissions.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -g @var{file}
|
|
+@opindex -g
|
|
+@cindex set-group-ID check
|
|
+True if @var{file} exists and has its set-group-ID bit set.
|
|
+
|
|
+@item -k @var{file}
|
|
+@opindex -k
|
|
+@cindex sticky bit check
|
|
+True if @var{file} exists and has its @dfn{sticky} bit set.
|
|
+
|
|
+@item -r @var{file}
|
|
+@opindex -r
|
|
+@cindex readable file check
|
|
+True if @var{file} exists and read permission is granted.
|
|
+
|
|
+@item -u @var{file}
|
|
+@opindex -u
|
|
+@cindex set-user-ID check
|
|
+True if @var{file} exists and has its set-user-ID bit set.
|
|
+
|
|
+@item -w @var{file}
|
|
+@opindex -w
|
|
+@cindex writable file check
|
|
+True if @var{file} exists and write permission is granted.
|
|
+
|
|
+@item -x @var{file}
|
|
+@opindex -x
|
|
+@cindex executable file check
|
|
+True if @var{file} exists and execute permission is granted
|
|
+(or search permission, if it is a directory).
|
|
+
|
|
+@item -O @var{file}
|
|
+@opindex -O
|
|
+@cindex owned by effective user ID check
|
|
+True if @var{file} exists and is owned by the current effective user ID.
|
|
+
|
|
+@item -G @var{file}
|
|
+@opindex -G
|
|
+@cindex owned by effective group ID check
|
|
+True if @var{file} exists and is owned by the current effective group ID.
|
|
+
|
|
+@end table
|
|
+
|
|
+@node File characteristic tests
|
|
+@subsection File characteristic tests
|
|
+
|
|
+@cindex file characteristic tests
|
|
+
|
|
+These options test other file characteristics.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -e @var{file}
|
|
+@opindex -e
|
|
+@cindex existence-of-file check
|
|
+True if @var{file} exists.
|
|
+
|
|
+@item -s @var{file}
|
|
+@opindex -s
|
|
+@cindex nonempty file check
|
|
+True if @var{file} exists and has a size greater than zero.
|
|
+
|
|
+@item @var{file1} -nt @var{file2}
|
|
+@opindex -nt
|
|
+@cindex newer-than file check
|
|
+True if @var{file1} is newer (according to modification date) than
|
|
+@var{file2}, or if @var{file1} exists and @var{file2} does not.
|
|
+
|
|
+@item @var{file1} -ot @var{file2}
|
|
+@opindex -ot
|
|
+@cindex older-than file check
|
|
+True if @var{file1} is older (according to modification date) than
|
|
+@var{file2}, or if @var{file2} exists and @var{file1} does not.
|
|
+
|
|
+@item @var{file1} -ef @var{file2}
|
|
+@opindex -ef
|
|
+@cindex same file check
|
|
+@cindex hard link check
|
|
+True if @var{file1} and @var{file2} have the same device and inode
|
|
+numbers, i.e., if they are hard links to each other.
|
|
+
|
|
+@end table
|
|
+
|
|
+
|
|
+@node String tests
|
|
+@subsection String tests
|
|
+
|
|
+@cindex string tests
|
|
+
|
|
+These options test string characteristics. You may need to quote
|
|
+@var{string} arguments for the shell. For example:
|
|
+
|
|
+@example
|
|
+test -n "$V"
|
|
+@end example
|
|
+
|
|
+The quotes here prevent the wrong arguments from being passed to
|
|
+@command{test} if @samp{$V} is empty or contains special characters.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -z @var{string}
|
|
+@opindex -z
|
|
+@cindex zero-length string check
|
|
+True if the length of @var{string} is zero.
|
|
+
|
|
+@item -n @var{string}
|
|
+@itemx @var{string}
|
|
+@opindex -n
|
|
+@cindex nonzero-length string check
|
|
+True if the length of @var{string} is nonzero.
|
|
+
|
|
+@item @var{string1} = @var{string2}
|
|
+@opindex =
|
|
+@cindex equal string check
|
|
+True if the strings are equal.
|
|
+
|
|
+@item @var{string1} != @var{string2}
|
|
+@opindex !=
|
|
+@cindex not-equal string check
|
|
+True if the strings are not equal.
|
|
+
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Numeric tests
|
|
+@subsection Numeric tests
|
|
+
|
|
+@cindex numeric tests
|
|
+@cindex arithmetic tests
|
|
+
|
|
+Numeric relational operators. The arguments must be entirely numeric
|
|
+(possibly negative), or the special expression @w{@code{-l @var{string}}},
|
|
+which evaluates to the length of @var{string}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item @var{arg1} -eq @var{arg2}
|
|
+@itemx @var{arg1} -ne @var{arg2}
|
|
+@itemx @var{arg1} -lt @var{arg2}
|
|
+@itemx @var{arg1} -le @var{arg2}
|
|
+@itemx @var{arg1} -gt @var{arg2}
|
|
+@itemx @var{arg1} -ge @var{arg2}
|
|
+@opindex -eq
|
|
+@opindex -ne
|
|
+@opindex -lt
|
|
+@opindex -le
|
|
+@opindex -gt
|
|
+@opindex -ge
|
|
+These arithmetic binary operators return true if @var{arg1} is equal,
|
|
+not-equal, less-than, less-than-or-equal, greater-than, or
|
|
+greater-than-or-equal than @var{arg2}, respectively.
|
|
+
|
|
+@end table
|
|
+
|
|
+For example:
|
|
+
|
|
+@example
|
|
+test -1 -gt -2 && echo yes
|
|
+@result{} yes
|
|
+test -l abc -gt 1 && echo yes
|
|
+@result{} yes
|
|
+test 0x100 -eq 1
|
|
+@error{} test: integer expression expected before -eq
|
|
+@end example
|
|
+
|
|
+
|
|
+@node Connectives for test
|
|
+@subsection Connectives for @command{test}
|
|
+
|
|
+@cindex logical connectives
|
|
+@cindex connectives, logical
|
|
+
|
|
+The usual logical connectives.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item ! @var{expr}
|
|
+@opindex !
|
|
+True if @var{expr} is false.
|
|
+
|
|
+@item @var{expr1} -a @var{expr2}
|
|
+@opindex -a
|
|
+@cindex logical and operator
|
|
+@cindex and operator
|
|
+True if both @var{expr1} and @var{expr2} are true.
|
|
+
|
|
+@item @var{expr1} -o @var{expr2}
|
|
+@opindex -o
|
|
+@cindex logical or operator
|
|
+@cindex or operator
|
|
+True if either @var{expr1} or @var{expr2} is true.
|
|
+
|
|
+@end table
|
|
+
|
|
+
|
|
+@node expr invocation
|
|
+@section @command{expr}: Evaluate expressions
|
|
+
|
|
+@pindex expr
|
|
+@cindex expression evaluation
|
|
+@cindex evaluation of expressions
|
|
+
|
|
+@command{expr} evaluates an expression and writes the result on standard
|
|
+output. Each token of the expression must be a separate argument.
|
|
+
|
|
+Operands are either integers or strings. Integers consist of one or
|
|
+more decimal digits, with an optional leading @samp{-}.
|
|
+@command{expr} converts
|
|
+anything appearing in an operand position to an integer or a string
|
|
+depending on the operation being applied to it.
|
|
+
|
|
+Strings are not quoted for @command{expr} itself, though you may need to
|
|
+quote them to protect characters with special meaning to the shell,
|
|
+e.g., spaces. However, regardless of whether it is quoted, a string
|
|
+operand should not be a parenthesis or any of @command{expr}'s
|
|
+operators like @code{+}, so you cannot safely pass an arbitrary string
|
|
+@code{$str} to expr merely by quoting it to the shell. One way to
|
|
+work around this is to use the @sc{gnu} extension @code{+},
|
|
+(e.g., @code{+ "$str" = foo}); a more portable way is to use
|
|
+@code{@w{" $str"}} and to adjust the rest of the expression to take
|
|
+the leading space into account (e.g., @code{@w{" $str" = " foo"}}).
|
|
+
|
|
+You should not pass a negative integer or a string with leading
|
|
+@samp{-} as @command{expr}'s first argument, as it might be
|
|
+misinterpreted as an option; this can be avoided by parenthesization.
|
|
+Also, portable scripts should not use a string operand that happens to
|
|
+take the form of an integer; this can be worked around by inserting
|
|
+leading spaces as mentioned above.
|
|
+
|
|
+@cindex parentheses for grouping
|
|
+Operators may be given as infix symbols or prefix keywords. Parentheses
|
|
+may be used for grouping in the usual manner. You must quote
|
|
+parentheses and many operators to avoid the shell evaluating them,
|
|
+however.
|
|
+
|
|
+When built with support for the GNU MP library, @command{expr} uses
|
|
+arbitrary-precision arithmetic; otherwise, it uses native arithmetic
|
|
+types and may fail due to arithmetic overflow.
|
|
+
|
|
+The only options are @option{--help} and @option{--version}. @xref{Common
|
|
+options}. Options must precede operands.
|
|
+
|
|
+@cindex exit status of @command{expr}
|
|
+Exit status:
|
|
+
|
|
+@display
|
|
+0 if the expression is neither null nor 0,
|
|
+1 if the expression is null or 0,
|
|
+2 if the expression is invalid,
|
|
+3 if an internal error occurred (e.g., arithmetic overflow).
|
|
+@end display
|
|
+
|
|
+@menu
|
|
+* String expressions:: + : match substr index length
|
|
+* Numeric expressions:: + - * / %
|
|
+* Relations for expr:: | & < <= = == != >= >
|
|
+* Examples of expr:: Examples.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node String expressions
|
|
+@subsection String expressions
|
|
+
|
|
+@cindex string expressions
|
|
+@cindex expressions, string
|
|
+
|
|
+@command{expr} supports pattern matching and other string operators. These
|
|
+have higher precedence than both the numeric and relational operators (in
|
|
+the next sections).
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item @var{string} : @var{regex}
|
|
+@cindex pattern matching
|
|
+@cindex regular expression matching
|
|
+@cindex matching patterns
|
|
+Perform pattern matching. The arguments are converted to strings and the
|
|
+second is considered to be a (basic, a la GNU @code{grep}) regular
|
|
+expression, with a @code{^} implicitly prepended. The first argument is
|
|
+then matched against this regular expression.
|
|
+
|
|
+If the match succeeds and @var{regex} uses @samp{\(} and @samp{\)}, the
|
|
+@code{:} expression returns the part of @var{string} that matched the
|
|
+subexpression; otherwise, it returns the number of characters matched.
|
|
+
|
|
+If the match fails, the @code{:} operator returns the null string if
|
|
+@samp{\(} and @samp{\)} are used in @var{regex}, otherwise 0.
|
|
+
|
|
+@kindex \( @r{regexp operator}
|
|
+Only the first @samp{\( @dots{} \)} pair is relevant to the return
|
|
+value; additional pairs are meaningful only for grouping the regular
|
|
+expression operators.
|
|
+
|
|
+@kindex \+ @r{regexp operator}
|
|
+@kindex \? @r{regexp operator}
|
|
+@kindex \| @r{regexp operator}
|
|
+In the regular expression, @code{\+}, @code{\?}, and @code{\|} are
|
|
+operators which respectively match one or more, zero or one, or separate
|
|
+alternatives. SunOS and other @command{expr}'s treat these as regular
|
|
+characters. (@acronym{POSIX} allows either behavior.)
|
|
+@xref{Top, , Regular Expression Library, regex, Regex}, for details of
|
|
+regular expression syntax. Some examples are in @ref{Examples of expr}.
|
|
+
|
|
+@item match @var{string} @var{regex}
|
|
+@findex match
|
|
+An alternative way to do pattern matching. This is the same as
|
|
+@w{@samp{@var{string} : @var{regex}}}.
|
|
+
|
|
+@item substr @var{string} @var{position} @var{length}
|
|
+@findex substr
|
|
+Returns the substring of @var{string} beginning at @var{position}
|
|
+with length at most @var{length}. If either @var{position} or
|
|
+@var{length} is negative, zero, or non-numeric, returns the null string.
|
|
+
|
|
+@item index @var{string} @var{charset}
|
|
+@findex index
|
|
+Returns the first position in @var{string} where the first character in
|
|
+@var{charset} was found. If no character in @var{charset} is found in
|
|
+@var{string}, return 0.
|
|
+
|
|
+@item length @var{string}
|
|
+@findex length
|
|
+Returns the length of @var{string}.
|
|
+
|
|
+@item + @var{token}
|
|
+@kindex +
|
|
+Interpret @var{token} as a string, even if it is a keyword like @var{match}
|
|
+or an operator like @code{/}.
|
|
+This makes it possible to test @code{expr length + "$x"} or
|
|
+@code{expr + "$x" : '.*/\(.\)'} and have it do the right thing even if
|
|
+the value of @var{$x} happens to be (for example) @code{/} or @code{index}.
|
|
+This operator is a @acronym{GNU} extension. Portable shell scripts should use
|
|
+@code{@w{" $token"} : @w{' \(.*\)'}} instead of @code{+ "$token"}.
|
|
+
|
|
+@end table
|
|
+
|
|
+To make @command{expr} interpret keywords as strings, you must use the
|
|
+@code{quote} operator.
|
|
+
|
|
+
|
|
+@node Numeric expressions
|
|
+@subsection Numeric expressions
|
|
+
|
|
+@cindex numeric expressions
|
|
+@cindex expressions, numeric
|
|
+
|
|
+@command{expr} supports the usual numeric operators, in order of increasing
|
|
+precedence. These numeric operators have lower precedence than the
|
|
+string operators described in the previous section, and higher precedence
|
|
+than the connectives (next section).
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item + -
|
|
+@kindex +
|
|
+@kindex -
|
|
+@cindex addition
|
|
+@cindex subtraction
|
|
+Addition and subtraction. Both arguments are converted to integers;
|
|
+an error occurs if this cannot be done.
|
|
+
|
|
+@item * / %
|
|
+@kindex *
|
|
+@kindex /
|
|
+@kindex %
|
|
+@cindex multiplication
|
|
+@cindex division
|
|
+@cindex remainder
|
|
+Multiplication, division, remainder. Both arguments are converted to
|
|
+integers; an error occurs if this cannot be done.
|
|
+
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Relations for expr
|
|
+@subsection Relations for @command{expr}
|
|
+
|
|
+@cindex connectives, logical
|
|
+@cindex logical connectives
|
|
+@cindex relations, numeric or string
|
|
+
|
|
+@command{expr} supports the usual logical connectives and relations. These
|
|
+have lower precedence than the string and numeric operators
|
|
+(previous sections). Here is the list, lowest-precedence operator first.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item |
|
|
+@kindex |
|
|
+@cindex logical or operator
|
|
+@cindex or operator
|
|
+Returns its first argument if that is neither null nor zero, otherwise
|
|
+its second argument if it is neither null nor zero, otherwise 0. It
|
|
+does not evaluate its second argument if its first argument is neither
|
|
+null nor zero.
|
|
+
|
|
+@item &
|
|
+@kindex &
|
|
+@cindex logical and operator
|
|
+@cindex and operator
|
|
+Return its first argument if neither argument is null or zero, otherwise
|
|
+0. It does not evaluate its second argument if its first argument is
|
|
+null or zero.
|
|
+
|
|
+@item < <= = == != >= >
|
|
+@kindex <
|
|
+@kindex <=
|
|
+@kindex =
|
|
+@kindex ==
|
|
+@kindex >
|
|
+@kindex >=
|
|
+@cindex comparison operators
|
|
+@vindex LC_COLLATE
|
|
+Compare the arguments and return 1 if the relation is true, 0 otherwise.
|
|
+@code{==} is a synonym for @code{=}. @command{expr} first tries to convert
|
|
+both arguments to integers and do a numeric comparison; if either
|
|
+conversion fails, it does a lexicographic comparison using the character
|
|
+collating sequence specified by the @env{LC_COLLATE} locale.
|
|
+
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Examples of expr
|
|
+@subsection Examples of using @command{expr}
|
|
+
|
|
+@cindex examples of @command{expr}
|
|
+Here are a few examples, including quoting for shell metacharacters.
|
|
+
|
|
+To add 1 to the shell variable @code{foo}, in Bourne-compatible shells:
|
|
+
|
|
+@example
|
|
+foo=`expr $foo + 1`
|
|
+@end example
|
|
+
|
|
+To print the non-directory part of the file name stored in
|
|
+@code{$fname}, which need not contain a @code{/}:
|
|
+
|
|
+@example
|
|
+expr $fname : '.*/\(.*\)' '|' $fname
|
|
+@end example
|
|
+
|
|
+An example showing that @code{\+} is an operator:
|
|
+
|
|
+@example
|
|
+expr aaa : 'a\+'
|
|
+@result{} 3
|
|
+@end example
|
|
+
|
|
+@example
|
|
+expr abc : 'a\(.\)c'
|
|
+@result{} b
|
|
+expr index abcdef cz
|
|
+@result{} 3
|
|
+expr index index a
|
|
+@error{} expr: syntax error
|
|
+expr index + index a
|
|
+@result{} 0
|
|
+@end example
|
|
+
|
|
+
|
|
+@node Redirection
|
|
+@chapter Redirection
|
|
+
|
|
+@cindex redirection
|
|
+@cindex commands for redirection
|
|
+
|
|
+Unix shells commonly provide several forms of @dfn{redirection}---ways
|
|
+to change the input source or output destination of a command. But one
|
|
+useful redirection is performed by a separate command, not by the shell;
|
|
+it's described here.
|
|
+
|
|
+@menu
|
|
+* tee invocation:: Redirect output to multiple files or processes.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node tee invocation
|
|
+@section @command{tee}: Redirect output to multiple files or processes
|
|
+
|
|
+@pindex tee
|
|
+@cindex pipe fitting
|
|
+@cindex destinations, multiple output
|
|
+@cindex read from stdin and write to stdout and files
|
|
+
|
|
+The @command{tee} command copies standard input to standard output and also
|
|
+to any files given as arguments. This is useful when you want not only
|
|
+to send some data down a pipe, but also to save a copy. Synopsis:
|
|
+
|
|
+@example
|
|
+tee [@var{option}]@dots{} [@var{file}]@dots{}
|
|
+@end example
|
|
+
|
|
+If a file being written to does not already exist, it is created. If a
|
|
+file being written to already exists, the data it previously contained
|
|
+is overwritten unless the @option{-a} option is used.
|
|
+
|
|
+A @var{file} of @samp{-} causes @command{tee} to send another copy of
|
|
+input to standard output, but this is typically not that useful as the
|
|
+copies are interleaved.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+@item -a
|
|
+@itemx --append
|
|
+@opindex -a
|
|
+@opindex --append
|
|
+Append standard input to the given files rather than overwriting
|
|
+them.
|
|
+
|
|
+@item -i
|
|
+@itemx --ignore-interrupts
|
|
+@opindex -i
|
|
+@opindex --ignore-interrupts
|
|
+Ignore interrupt signals.
|
|
+
|
|
+@end table
|
|
+
|
|
+The @command{tee} command is useful when you happen to be transferring a large
|
|
+amount of data and also want to summarize that data without reading
|
|
+it a second time. For example, when you are downloading a DVD image,
|
|
+you often want to verify its signature or checksum right away.
|
|
+The inefficient way to do it is simply:
|
|
+
|
|
+@example
|
|
+wget http://example.com/some.iso && sha1sum some.iso
|
|
+@end example
|
|
+
|
|
+One problem with the above is that it makes you wait for the
|
|
+download to complete before starting the time-consuming SHA1 computation.
|
|
+Perhaps even more importantly, the above requires reading
|
|
+the DVD image a second time (the first was from the network).
|
|
+
|
|
+The efficient way to do it is to interleave the download
|
|
+and SHA1 computation. Then, you'll get the checksum for
|
|
+free, because the entire process parallelizes so well:
|
|
+
|
|
+@example
|
|
+# slightly contrived, to demonstrate process substitution
|
|
+wget -O - http://example.com/dvd.iso \
|
|
+ | tee >(sha1sum > dvd.sha1) > dvd.iso
|
|
+@end example
|
|
+
|
|
+That makes @command{tee} write not just to the expected output file,
|
|
+but also to a pipe running @command{sha1sum} and saving the final
|
|
+checksum in a file named @file{dvd.sha1}.
|
|
+
|
|
+Note, however, that this example relies on a feature of modern shells
|
|
+called @dfn{process substitution}
|
|
+(the @samp{>(command)} syntax, above;
|
|
+@xref{Process Substitution,,Process Substitution, bashref,
|
|
+The Bash Reference Manual}.),
|
|
+so it works with @command{zsh}, @command{bash}, and @command{ksh},
|
|
+but not with @command{/bin/sh}. So if you write code like this
|
|
+in a shell script, be sure to start the script with @samp{#!/bin/bash}.
|
|
+
|
|
+Since the above example writes to one file and one process,
|
|
+a more conventional and portable use of @command{tee} is even better:
|
|
+
|
|
+@example
|
|
+wget -O - http://example.com/dvd.iso \
|
|
+ | tee dvd.iso | sha1sum > dvd.sha1
|
|
+@end example
|
|
+
|
|
+You can extend this example to make @command{tee} write to two processes,
|
|
+computing MD5 and SHA1 checksums in parallel. In this case,
|
|
+process substitution is required:
|
|
+
|
|
+@example
|
|
+wget -O - http://example.com/dvd.iso \
|
|
+ | tee >(sha1sum > dvd.sha1) \
|
|
+ >(md5sum > dvd.md5) \
|
|
+ > dvd.iso
|
|
+@end example
|
|
+
|
|
+This technique is also useful when you want to make a @emph{compressed}
|
|
+copy of the contents of a pipe.
|
|
+Consider a tool to graphically summarize disk usage data from @samp{du -ak}.
|
|
+For a large hierarchy, @samp{du -ak} can run for a long time,
|
|
+and can easily produce terabytes of data, so you won't want to
|
|
+rerun the command unnecessarily. Nor will you want to save
|
|
+the uncompressed output.
|
|
+
|
|
+Doing it the inefficient way, you can't even start the GUI
|
|
+until after you've compressed all of the @command{du} output:
|
|
+
|
|
+@example
|
|
+du -ak | gzip -9 > /tmp/du.gz
|
|
+gzip -d /tmp/du.gz | xdiskusage -a
|
|
+@end example
|
|
+
|
|
+With @command{tee} and process substitution, you start the GUI
|
|
+right away and eliminate the decompression completely:
|
|
+
|
|
+@example
|
|
+du -ak | tee >(gzip -9 > /tmp/du.gz) | xdiskusage -a
|
|
+@end example
|
|
+
|
|
+Finally, if you regularly create more than one type of
|
|
+compressed tarball at once, for example when @code{make dist} creates
|
|
+both @command{gzip}-compressed and @command{bzip2}-compressed tarballs,
|
|
+there may be a better way.
|
|
+Typical @command{automake}-generated @file{Makefile} rules create
|
|
+the two compressed tar archives with commands in sequence, like this
|
|
+(slightly simplified):
|
|
+
|
|
+@example
|
|
+tardir=your-pkg-M.N
|
|
+tar chof - "$tardir" | gzip -9 -c > your-pkg-M.N.tar.gz
|
|
+tar chof - "$tardir" | bzip2 -9 -c > your-pkg-M.N.tar.bz2
|
|
+@end example
|
|
+
|
|
+However, if the hierarchy you are archiving and compressing is larger
|
|
+than a couple megabytes, and especially if you are using a multi-processor
|
|
+system with plenty of memory, then you can do much better by reading the
|
|
+directory contents only once and running the compression programs in parallel:
|
|
+
|
|
+@example
|
|
+tardir=your-pkg-M.N
|
|
+tar chof - "$tardir" \
|
|
+ | tee >(gzip -9 -c > your-pkg-M.N.tar.gz) \
|
|
+ | bzip2 -9 -c > your-pkg-M.N.tar.bz2
|
|
+@end example
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node File name manipulation
|
|
+@chapter File name manipulation
|
|
+
|
|
+@cindex file name manipulation
|
|
+@cindex manipulation of file names
|
|
+@cindex commands for file name manipulation
|
|
+
|
|
+This section describes commands that manipulate file names.
|
|
+
|
|
+@menu
|
|
+* 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.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node basename invocation
|
|
+@section @command{basename}: Strip directory and suffix from a file name
|
|
+
|
|
+@pindex basename
|
|
+@cindex strip directory and suffix from file names
|
|
+@cindex directory, stripping from file names
|
|
+@cindex suffix, stripping from file names
|
|
+@cindex file names, stripping directory and suffix
|
|
+@cindex leading directory components, stripping
|
|
+
|
|
+@command{basename} removes any leading directory components from
|
|
+@var{name}. Synopsis:
|
|
+
|
|
+@example
|
|
+basename @var{name} [@var{suffix}]
|
|
+@end example
|
|
+
|
|
+If @var{suffix} is specified and is identical to the end of @var{name},
|
|
+it is removed from @var{name} as well. Note that since trailing slashes
|
|
+are removed prior to suffix matching, @var{suffix} will do nothing if it
|
|
+contains slashes. @command{basename} prints the result on standard
|
|
+output.
|
|
+
|
|
+@c This test is used both here and in the section on dirname.
|
|
+@macro basenameAndDirname
|
|
+Together, @command{basename} and @command{dirname} are designed such
|
|
+that if @samp{ls "$name"} succeeds, then the command sequence @samp{cd
|
|
+"$(dirname "$name")"; ls "$(basename "$name")"} will, too. This works
|
|
+for everything except file names containing a trailing newline.
|
|
+@end macro
|
|
+@basenameAndDirname
|
|
+
|
|
+@acronym{POSIX} allows the implementation to define the results if
|
|
+@var{name} is empty or @samp{//}. In the former case, @acronym{GNU}
|
|
+@command{basename} returns the empty string. In the latter case, the
|
|
+result is @samp{//} on platforms where @var{//} is distinct from
|
|
+@var{/}, and @samp{/} on platforms where there is no difference.
|
|
+
|
|
+The only options are @option{--help} and @option{--version}. @xref{Common
|
|
+options}. Options must precede operands.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+Examples:
|
|
+
|
|
+@smallexample
|
|
+# Output "sort".
|
|
+basename /usr/bin/sort
|
|
+
|
|
+# Output "stdio".
|
|
+basename include/stdio.h .h
|
|
+@end smallexample
|
|
+
|
|
+
|
|
+@node dirname invocation
|
|
+@section @command{dirname}: Strip non-directory suffix from a file name
|
|
+
|
|
+@pindex dirname
|
|
+@cindex directory components, printing
|
|
+@cindex stripping non-directory suffix
|
|
+@cindex non-directory suffix, stripping
|
|
+
|
|
+@command{dirname} prints all but the final slash-delimited component of
|
|
+a string (presumably a file name). Synopsis:
|
|
+
|
|
+@example
|
|
+dirname @var{name}
|
|
+@end example
|
|
+
|
|
+If @var{name} is a single component, @command{dirname} prints @samp{.}
|
|
+(meaning the current directory).
|
|
+
|
|
+@basenameAndDirname
|
|
+
|
|
+@acronym{POSIX} allows the implementation to define the results if
|
|
+@var{name} is @samp{//}. With @acronym{GNU} @command{dirname}, the
|
|
+result is @samp{//} on platforms where @var{//} is distinct from
|
|
+@var{/}, and @samp{/} on platforms where there is no difference.
|
|
+
|
|
+The only options are @option{--help} and @option{--version}. @xref{Common
|
|
+options}.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+Examples:
|
|
+
|
|
+@smallexample
|
|
+# Output "/usr/bin".
|
|
+dirname /usr/bin/sort
|
|
+
|
|
+# Output ".".
|
|
+dirname stdio.h
|
|
+@end smallexample
|
|
+
|
|
+
|
|
+@node pathchk invocation
|
|
+@section @command{pathchk}: Check file name validity and portability
|
|
+
|
|
+@pindex pathchk
|
|
+@cindex file names, checking validity and portability
|
|
+@cindex valid file names, checking for
|
|
+@cindex portable file names, checking for
|
|
+
|
|
+@command{pathchk} checks validity and portability of file names. Synopsis:
|
|
+
|
|
+@example
|
|
+pathchk [@var{option}]@dots{} @var{name}@dots{}
|
|
+@end example
|
|
+
|
|
+For each @var{name}, @command{pathchk} prints an error message if any of
|
|
+these conditions is true:
|
|
+
|
|
+@enumerate
|
|
+@item
|
|
+One of the existing directories in @var{name} does not have search
|
|
+(execute) permission,
|
|
+@item
|
|
+The length of @var{name} is larger than the maximum supported by the
|
|
+operating system.
|
|
+@item
|
|
+The length of one component of @var{name} is longer than
|
|
+its file system's maximum.
|
|
+@end enumerate
|
|
+
|
|
+A nonexistent @var{name} is not an error, so long a file with that
|
|
+name could be created under the above conditions.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+Options must precede operands.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -p
|
|
+@opindex -p
|
|
+Instead of performing checks based on the underlying file system,
|
|
+print an error message if any of these conditions is true:
|
|
+
|
|
+@enumerate
|
|
+@item
|
|
+A file name is empty.
|
|
+
|
|
+@item
|
|
+A file name contains a character outside the @acronym{POSIX} portable file
|
|
+name character set, namely, the ASCII letters and digits, @samp{.},
|
|
+@samp{_}, @samp{-}, and @samp{/}.
|
|
+
|
|
+@item
|
|
+The length of a file name or one of its components exceeds the
|
|
+@acronym{POSIX} minimum limits for portability.
|
|
+@end enumerate
|
|
+
|
|
+@item -P
|
|
+@opindex -P
|
|
+Print an error message if a file name is empty, or if it contains a component
|
|
+that begins with @samp{-}.
|
|
+
|
|
+@item --portability
|
|
+@opindex --portability
|
|
+Print an error message if a file name is not portable to all @acronym{POSIX}
|
|
+hosts. This option is equivalent to @samp{-p -P}.
|
|
+
|
|
+@end table
|
|
+
|
|
+@cindex exit status of @command{pathchk}
|
|
+Exit status:
|
|
+
|
|
+@display
|
|
+0 if all specified file names passed all checks,
|
|
+1 otherwise.
|
|
+@end display
|
|
+
|
|
+
|
|
+@node Working context
|
|
+@chapter Working context
|
|
+
|
|
+@cindex working context
|
|
+@cindex commands for printing the working context
|
|
+
|
|
+This section describes commands that display or alter the context in
|
|
+which you are working: the current directory, the terminal settings, and
|
|
+so forth. See also the user-related commands in the next section.
|
|
+
|
|
+@menu
|
|
+* pwd invocation:: Print working directory.
|
|
+* stty invocation:: Print or change terminal characteristics.
|
|
+* printenv invocation:: Print environment variables.
|
|
+* tty invocation:: Print file name of terminal on standard input.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node pwd invocation
|
|
+@section @command{pwd}: Print working directory
|
|
+
|
|
+@pindex pwd
|
|
+@cindex print name of current directory
|
|
+@cindex current working directory, printing
|
|
+@cindex working directory, printing
|
|
+
|
|
+
|
|
+@command{pwd} prints the name of the current directory. Synopsis:
|
|
+
|
|
+@example
|
|
+pwd [@var{option}]@dots{}
|
|
+@end example
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+@item -L
|
|
+@itemx --logical
|
|
+@opindex -L
|
|
+@opindex --logical
|
|
+If the contents of the environment variable @env{PWD} provide an
|
|
+absolute name of the current directory with no @samp{.} or @samp{..}
|
|
+components, but possibly with symbolic links, then output those
|
|
+contents. Otherwise, fall back to default @option{-P} handling.
|
|
+
|
|
+@item -P
|
|
+@itemx --physical
|
|
+@opindex -P
|
|
+@opindex --physical
|
|
+Print a fully resolved name for the current directory. That is, all
|
|
+components of the printed name will be actual directory names---none
|
|
+will be symbolic links.
|
|
+@end table
|
|
+
|
|
+@cindex symbolic links and @command{pwd}
|
|
+If @option{-L} and @option{-P} are both given, the last one takes
|
|
+precedence. If neither option is given, then this implementation uses
|
|
+@option{-P} as the default unless the @env{POSIXLY_CORRECT}
|
|
+environment variable is set.
|
|
+
|
|
+@mayConflictWithShellBuiltIn{pwd}
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node stty invocation
|
|
+@section @command{stty}: Print or change terminal characteristics
|
|
+
|
|
+@pindex stty
|
|
+@cindex change or print terminal settings
|
|
+@cindex terminal settings
|
|
+@cindex line settings of terminal
|
|
+
|
|
+@command{stty} prints or changes terminal characteristics, such as baud rate.
|
|
+Synopses:
|
|
+
|
|
+@example
|
|
+stty [@var{option}] [@var{setting}]@dots{}
|
|
+stty [@var{option}]
|
|
+@end example
|
|
+
|
|
+If given no line settings, @command{stty} prints the baud rate, line
|
|
+discipline number (on systems that support it), and line settings
|
|
+that have been changed from the values set by @samp{stty sane}.
|
|
+By default, mode reading and setting are performed on the tty line
|
|
+connected to standard input, although this can be modified by the
|
|
+@option{--file} option.
|
|
+
|
|
+@command{stty} accepts many non-option arguments that change aspects of
|
|
+the terminal line operation, as described below.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+@item -a
|
|
+@itemx --all
|
|
+@opindex -a
|
|
+@opindex --all
|
|
+Print all current settings in human-readable form. This option may not
|
|
+be used in combination with any line settings.
|
|
+
|
|
+@item -F @var{device}
|
|
+@itemx --file=@var{device}
|
|
+@opindex -F
|
|
+@opindex --file
|
|
+Set the line opened by the file name specified in @var{device} instead of
|
|
+the tty line connected to standard input. This option is necessary
|
|
+because opening a @acronym{POSIX} tty requires use of the @code{O_NONDELAY} flag to
|
|
+prevent a @acronym{POSIX} tty from blocking until the carrier detect line is high if
|
|
+the @code{clocal} flag is not set. Hence, it is not always possible
|
|
+to allow the shell to open the device in the traditional manner.
|
|
+
|
|
+@item -g
|
|
+@itemx --save
|
|
+@opindex -g
|
|
+@opindex --save
|
|
+@cindex machine-readable @command{stty} output
|
|
+Print all current settings in a form that can be used as an argument to
|
|
+another @command{stty} command to restore the current settings. This option
|
|
+may not be used in combination with any line settings.
|
|
+
|
|
+@end table
|
|
+
|
|
+Many settings can be turned off by preceding them with a @samp{-}.
|
|
+Such arguments are marked below with ``May be negated'' in their
|
|
+description. The descriptions themselves refer to the positive
|
|
+case, that is, when @emph{not} negated (unless stated otherwise,
|
|
+of course).
|
|
+
|
|
+Some settings are not available on all @acronym{POSIX} systems, since they use
|
|
+extensions. Such arguments are marked below with ``Non-@acronym{POSIX}'' in their
|
|
+description. On non-@acronym{POSIX} systems, those or other settings also may not
|
|
+be available, but it's not feasible to document all the variations: just
|
|
+try it and see.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+@menu
|
|
+* Control:: Control settings
|
|
+* Input:: Input settings
|
|
+* Output:: Output settings
|
|
+* Local:: Local settings
|
|
+* Combination:: Combination settings
|
|
+* Characters:: Special characters
|
|
+* Special:: Special settings
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node Control
|
|
+@subsection Control settings
|
|
+
|
|
+@cindex control settings
|
|
+Control settings:
|
|
+
|
|
+@table @samp
|
|
+@item parenb
|
|
+@opindex parenb
|
|
+@cindex two-way parity
|
|
+Generate parity bit in output and expect parity bit in input.
|
|
+May be negated.
|
|
+
|
|
+@item parodd
|
|
+@opindex parodd
|
|
+@cindex odd parity
|
|
+@cindex even parity
|
|
+Set odd parity (even if negated). May be negated.
|
|
+
|
|
+@item cs5
|
|
+@itemx cs6
|
|
+@itemx cs7
|
|
+@itemx cs8
|
|
+@opindex cs@var{n}
|
|
+@cindex character size
|
|
+@cindex eight-bit characters
|
|
+Set character size to 5, 6, 7, or 8 bits.
|
|
+
|
|
+@item hup
|
|
+@itemx hupcl
|
|
+@opindex hup[cl]
|
|
+Send a hangup signal when the last process closes the tty. May be
|
|
+negated.
|
|
+
|
|
+@item cstopb
|
|
+@opindex cstopb
|
|
+@cindex stop bits
|
|
+Use two stop bits per character (one if negated). May be negated.
|
|
+
|
|
+@item cread
|
|
+@opindex cread
|
|
+Allow input to be received. May be negated.
|
|
+
|
|
+@item clocal
|
|
+@opindex clocal
|
|
+@cindex modem control
|
|
+Disable modem control signals. May be negated.
|
|
+
|
|
+@item crtscts
|
|
+@opindex crtscts
|
|
+@cindex hardware flow control
|
|
+@cindex flow control, hardware
|
|
+@cindex RTS/CTS flow control
|
|
+Enable RTS/CTS flow control. Non-@acronym{POSIX}. May be negated.
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Input
|
|
+@subsection Input settings
|
|
+
|
|
+@cindex input settings
|
|
+These settings control operations on data received from the terminal.
|
|
+
|
|
+@table @samp
|
|
+@item ignbrk
|
|
+@opindex ignbrk
|
|
+@cindex breaks, ignoring
|
|
+Ignore break characters. May be negated.
|
|
+
|
|
+@item brkint
|
|
+@opindex brkint
|
|
+@cindex breaks, cause interrupts
|
|
+Make breaks cause an interrupt signal. May be negated.
|
|
+
|
|
+@item ignpar
|
|
+@opindex ignpar
|
|
+@cindex parity, ignoring
|
|
+Ignore characters with parity errors. May be negated.
|
|
+
|
|
+@item parmrk
|
|
+@opindex parmrk
|
|
+@cindex parity errors, marking
|
|
+Mark parity errors (with a 255-0-character sequence). May be negated.
|
|
+
|
|
+@item inpck
|
|
+@opindex inpck
|
|
+Enable input parity checking. May be negated.
|
|
+
|
|
+@item istrip
|
|
+@opindex istrip
|
|
+@cindex eight-bit input
|
|
+Clear high (8th) bit of input characters. May be negated.
|
|
+
|
|
+@item inlcr
|
|
+@opindex inlcr
|
|
+@cindex newline, translating to return
|
|
+Translate newline to carriage return. May be negated.
|
|
+
|
|
+@item igncr
|
|
+@opindex igncr
|
|
+@cindex return, ignoring
|
|
+Ignore carriage return. May be negated.
|
|
+
|
|
+@item icrnl
|
|
+@opindex icrnl
|
|
+@cindex return, translating to newline
|
|
+Translate carriage return to newline. May be negated.
|
|
+
|
|
+@item iutf8
|
|
+@opindex iutf8
|
|
+@cindex input encoding, UTF-8
|
|
+Assume input characters are UTF-8 encoded. May be negated.
|
|
+
|
|
+@item ixon
|
|
+@opindex ixon
|
|
+@kindex C-s/C-q flow control
|
|
+@cindex XON/XOFF flow control
|
|
+Enable XON/XOFF flow control (that is, @kbd{CTRL-S}/@kbd{CTRL-Q}). May
|
|
+be negated.
|
|
+
|
|
+@item ixoff
|
|
+@itemx tandem
|
|
+@opindex ixoff
|
|
+@opindex tandem
|
|
+@cindex software flow control
|
|
+@cindex flow control, software
|
|
+Enable sending of @code{stop} character when the system input buffer
|
|
+is almost full, and @code{start} character when it becomes almost
|
|
+empty again. May be negated.
|
|
+
|
|
+@item iuclc
|
|
+@opindex iuclc
|
|
+@cindex uppercase, translating to lowercase
|
|
+Translate uppercase characters to lowercase. Non-@acronym{POSIX}. May be
|
|
+negated. Note ilcuc is not implemented, as one would not be able to issue
|
|
+almost any (lowercase) Unix command, after invoking it.
|
|
+
|
|
+@item ixany
|
|
+@opindex ixany
|
|
+Allow any character to restart output (only the start character
|
|
+if negated). Non-@acronym{POSIX}. May be negated.
|
|
+
|
|
+@item imaxbel
|
|
+@opindex imaxbel
|
|
+@cindex beeping at input buffer full
|
|
+Enable beeping and not flushing input buffer if a character arrives
|
|
+when the input buffer is full. Non-@acronym{POSIX}. May be negated.
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Output
|
|
+@subsection Output settings
|
|
+
|
|
+@cindex output settings
|
|
+These settings control operations on data sent to the terminal.
|
|
+
|
|
+@table @samp
|
|
+@item opost
|
|
+@opindex opost
|
|
+Postprocess output. May be negated.
|
|
+
|
|
+@item olcuc
|
|
+@opindex olcuc
|
|
+@cindex lowercase, translating to output
|
|
+Translate lowercase characters to uppercase. Non-@acronym{POSIX}. May be
|
|
+negated. (Note ouclc is not currently implemented.)
|
|
+
|
|
+@item ocrnl
|
|
+@opindex ocrnl
|
|
+@cindex return, translating to newline
|
|
+Translate carriage return to newline. Non-@acronym{POSIX}. May be negated.
|
|
+
|
|
+@item onlcr
|
|
+@opindex onlcr
|
|
+@cindex newline, translating to crlf
|
|
+Translate newline to carriage return-newline. Non-@acronym{POSIX}. May be
|
|
+negated.
|
|
+
|
|
+@item onocr
|
|
+@opindex onocr
|
|
+Do not print carriage returns in the first column. Non-@acronym{POSIX}.
|
|
+May be negated.
|
|
+
|
|
+@item onlret
|
|
+@opindex onlret
|
|
+Newline performs a carriage return. Non-@acronym{POSIX}. May be negated.
|
|
+
|
|
+@item ofill
|
|
+@opindex ofill
|
|
+@cindex pad instead of timing for delaying
|
|
+Use fill (padding) characters instead of timing for delays. Non-@acronym{POSIX}.
|
|
+May be negated.
|
|
+
|
|
+@item ofdel
|
|
+@opindex ofdel
|
|
+@cindex pad character
|
|
+Use @acronym{ASCII} @sc{del} characters for fill instead of
|
|
+@acronym{ASCII} @sc{nul} characters. Non-@acronym{POSIX}.
|
|
+May be negated.
|
|
+
|
|
+@item nl1
|
|
+@itemx nl0
|
|
+@opindex nl@var{n}
|
|
+Newline delay style. Non-@acronym{POSIX}.
|
|
+
|
|
+@item cr3
|
|
+@itemx cr2
|
|
+@itemx cr1
|
|
+@itemx cr0
|
|
+@opindex cr@var{n}
|
|
+Carriage return delay style. Non-@acronym{POSIX}.
|
|
+
|
|
+@item tab3
|
|
+@itemx tab2
|
|
+@itemx tab1
|
|
+@itemx tab0
|
|
+@opindex tab@var{n}
|
|
+Horizontal tab delay style. Non-@acronym{POSIX}.
|
|
+
|
|
+@item bs1
|
|
+@itemx bs0
|
|
+@opindex bs@var{n}
|
|
+Backspace delay style. Non-@acronym{POSIX}.
|
|
+
|
|
+@item vt1
|
|
+@itemx vt0
|
|
+@opindex vt@var{n}
|
|
+Vertical tab delay style. Non-@acronym{POSIX}.
|
|
+
|
|
+@item ff1
|
|
+@itemx ff0
|
|
+@opindex ff@var{n}
|
|
+Form feed delay style. Non-@acronym{POSIX}.
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Local
|
|
+@subsection Local settings
|
|
+
|
|
+@cindex local settings
|
|
+
|
|
+@table @samp
|
|
+@item isig
|
|
+@opindex isig
|
|
+Enable @code{interrupt}, @code{quit}, and @code{suspend} special
|
|
+characters. May be negated.
|
|
+
|
|
+@item icanon
|
|
+@opindex icanon
|
|
+Enable @code{erase}, @code{kill}, @code{werase}, and @code{rprnt}
|
|
+special characters. May be negated.
|
|
+
|
|
+@item iexten
|
|
+@opindex iexten
|
|
+Enable non-@acronym{POSIX} special characters. May be negated.
|
|
+
|
|
+@item echo
|
|
+@opindex echo
|
|
+Echo input characters. May be negated.
|
|
+
|
|
+@item echoe
|
|
+@itemx crterase
|
|
+@opindex echoe
|
|
+@opindex crterase
|
|
+Echo @code{erase} characters as backspace-space-backspace. May be
|
|
+negated.
|
|
+
|
|
+@item echok
|
|
+@opindex echok
|
|
+@cindex newline echoing after @code{kill}
|
|
+Echo a newline after a @code{kill} character. May be negated.
|
|
+
|
|
+@item echonl
|
|
+@opindex echonl
|
|
+@cindex newline, echoing
|
|
+Echo newline even if not echoing other characters. May be negated.
|
|
+
|
|
+@item noflsh
|
|
+@opindex noflsh
|
|
+@cindex flushing, disabling
|
|
+Disable flushing after @code{interrupt} and @code{quit} special
|
|
+characters. May be negated.
|
|
+
|
|
+@item xcase
|
|
+@opindex xcase
|
|
+@cindex case translation
|
|
+Enable input and output of uppercase characters by preceding their
|
|
+lowercase equivalents with @samp{\}, when @code{icanon} is set.
|
|
+Non-@acronym{POSIX}. May be negated.
|
|
+
|
|
+@item tostop
|
|
+@opindex tostop
|
|
+@cindex background jobs, stopping at terminal write
|
|
+Stop background jobs that try to write to the terminal. Non-@acronym{POSIX}.
|
|
+May be negated.
|
|
+
|
|
+@item echoprt
|
|
+@itemx prterase
|
|
+@opindex echoprt
|
|
+@opindex prterase
|
|
+Echo erased characters backward, between @samp{\} and @samp{/}.
|
|
+Non-@acronym{POSIX}. May be negated.
|
|
+
|
|
+@item echoctl
|
|
+@itemx ctlecho
|
|
+@opindex echoctl
|
|
+@opindex ctlecho
|
|
+@cindex control characters, using @samp{^@var{c}}
|
|
+@cindex hat notation for control characters
|
|
+Echo control characters in hat notation (@samp{^@var{c}}) instead
|
|
+of literally. Non-@acronym{POSIX}. May be negated.
|
|
+
|
|
+@item echoke
|
|
+@itemx crtkill
|
|
+@opindex echoke
|
|
+@opindex crtkill
|
|
+Echo the @code{kill} special character by erasing each character on
|
|
+the line as indicated by the @code{echoprt} and @code{echoe} settings,
|
|
+instead of by the @code{echoctl} and @code{echok} settings. Non-@acronym{POSIX}.
|
|
+May be negated.
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Combination
|
|
+@subsection Combination settings
|
|
+
|
|
+@cindex combination settings
|
|
+Combination settings:
|
|
+
|
|
+@table @samp
|
|
+@item evenp
|
|
+@opindex evenp
|
|
+@itemx parity
|
|
+@opindex parity
|
|
+Same as @code{parenb -parodd cs7}. May be negated. If negated, same
|
|
+as @code{-parenb cs8}.
|
|
+
|
|
+@item oddp
|
|
+@opindex oddp
|
|
+Same as @code{parenb parodd cs7}. May be negated. If negated, same
|
|
+as @code{-parenb cs8}.
|
|
+
|
|
+@item nl
|
|
+@opindex nl
|
|
+Same as @code{-icrnl -onlcr}. May be negated. If negated, same as
|
|
+@code{icrnl -inlcr -igncr onlcr -ocrnl -onlret}.
|
|
+
|
|
+@item ek
|
|
+@opindex ek
|
|
+Reset the @code{erase} and @code{kill} special characters to their default
|
|
+values.
|
|
+
|
|
+@item sane
|
|
+@opindex sane
|
|
+Same as:
|
|
+
|
|
+@c This is too long to write inline.
|
|
+@example
|
|
+cread -ignbrk brkint -inlcr -igncr icrnl -ixoff
|
|
+-iuclc -ixany imaxbel opost -olcuc -ocrnl onlcr
|
|
+-onocr -onlret -ofill -ofdel nl0 cr0 tab0 bs0 vt0
|
|
+ff0 isig icanon iexten echo echoe echok -echonl
|
|
+-noflsh -xcase -tostop -echoprt echoctl echoke
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+and also sets all special characters to their default values.
|
|
+
|
|
+@item cooked
|
|
+@opindex cooked
|
|
+Same as @code{brkint ignpar istrip icrnl ixon opost isig icanon}, plus
|
|
+sets the @code{eof} and @code{eol} characters to their default values
|
|
+if they are the same as the @code{min} and @code{time} characters.
|
|
+May be negated. If negated, same as @code{raw}.
|
|
+
|
|
+@item raw
|
|
+@opindex raw
|
|
+Same as:
|
|
+
|
|
+@example
|
|
+-ignbrk -brkint -ignpar -parmrk -inpck -istrip
|
|
+-inlcr -igncr -icrnl -ixon -ixoff -iuclc -ixany
|
|
+-imaxbel -opost -isig -icanon -xcase min 1 time 0
|
|
+@end example
|
|
+
|
|
+@noindent
|
|
+May be negated. If negated, same as @code{cooked}.
|
|
+
|
|
+@item cbreak
|
|
+@opindex cbreak
|
|
+Same as @option{-icanon}. May be negated. If negated, same as
|
|
+@code{icanon}.
|
|
+
|
|
+@item pass8
|
|
+@opindex pass8
|
|
+@cindex eight-bit characters
|
|
+Same as @code{-parenb -istrip cs8}. May be negated. If negated,
|
|
+same as @code{parenb istrip cs7}.
|
|
+
|
|
+@item litout
|
|
+@opindex litout
|
|
+Same as @option{-parenb -istrip -opost cs8}. May be negated.
|
|
+If negated, same as @code{parenb istrip opost cs7}.
|
|
+
|
|
+@item decctlq
|
|
+@opindex decctlq
|
|
+Same as @option{-ixany}. Non-@acronym{POSIX}. May be negated.
|
|
+
|
|
+@item tabs
|
|
+@opindex tabs
|
|
+Same as @code{tab0}. Non-@acronym{POSIX}. May be negated. If negated, same
|
|
+as @code{tab3}.
|
|
+
|
|
+@item lcase
|
|
+@itemx LCASE
|
|
+@opindex lcase
|
|
+@opindex LCASE
|
|
+Same as @code{xcase iuclc olcuc}. Non-@acronym{POSIX}. May be negated.
|
|
+(Used for terminals with uppercase characters only.)
|
|
+
|
|
+@item crt
|
|
+@opindex crt
|
|
+Same as @code{echoe echoctl echoke}.
|
|
+
|
|
+@item dec
|
|
+@opindex dec
|
|
+Same as @code{echoe echoctl echoke -ixany intr ^C erase ^? kill C-u}.
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Characters
|
|
+@subsection Special characters
|
|
+
|
|
+@cindex special characters
|
|
+@cindex characters, special
|
|
+
|
|
+The special characters' default values vary from system to system.
|
|
+They are set with the syntax @samp{name value}, where the names are
|
|
+listed below and the value can be given either literally, in hat
|
|
+notation (@samp{^@var{c}}), or as an integer which may start with
|
|
+@samp{0x} to indicate hexadecimal, @samp{0} to indicate octal, or
|
|
+any other digit to indicate decimal.
|
|
+
|
|
+@cindex disabling special characters
|
|
+@kindex u@r{, and disabling special characters}
|
|
+For GNU stty, giving a value of @code{^-} or @code{undef} disables that
|
|
+special character. (This is incompatible with Ultrix @command{stty},
|
|
+which uses a value of @samp{u} to disable a special character. GNU
|
|
+@command{stty} treats a value @samp{u} like any other, namely to set that
|
|
+special character to @key{U}.)
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item intr
|
|
+@opindex intr
|
|
+Send an interrupt signal.
|
|
+
|
|
+@item quit
|
|
+@opindex quit
|
|
+Send a quit signal.
|
|
+
|
|
+@item erase
|
|
+@opindex erase
|
|
+Erase the last character typed.
|
|
+
|
|
+@item kill
|
|
+@opindex kill
|
|
+Erase the current line.
|
|
+
|
|
+@item eof
|
|
+@opindex eof
|
|
+Send an end of file (terminate the input).
|
|
+
|
|
+@item eol
|
|
+@opindex eol
|
|
+End the line.
|
|
+
|
|
+@item eol2
|
|
+@opindex eol2
|
|
+Alternate character to end the line. Non-@acronym{POSIX}.
|
|
+
|
|
+@item swtch
|
|
+@opindex swtch
|
|
+Switch to a different shell layer. Non-@acronym{POSIX}.
|
|
+
|
|
+@item start
|
|
+@opindex start
|
|
+Restart the output after stopping it.
|
|
+
|
|
+@item stop
|
|
+@opindex stop
|
|
+Stop the output.
|
|
+
|
|
+@item susp
|
|
+@opindex susp
|
|
+Send a terminal stop signal.
|
|
+
|
|
+@item dsusp
|
|
+@opindex dsusp
|
|
+Send a terminal stop signal after flushing the input. Non-@acronym{POSIX}.
|
|
+
|
|
+@item rprnt
|
|
+@opindex rprnt
|
|
+Redraw the current line. Non-@acronym{POSIX}.
|
|
+
|
|
+@item werase
|
|
+@opindex werase
|
|
+Erase the last word typed. Non-@acronym{POSIX}.
|
|
+
|
|
+@item lnext
|
|
+@opindex lnext
|
|
+Enter the next character typed literally, even if it is a special
|
|
+character. Non-@acronym{POSIX}.
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Special
|
|
+@subsection Special settings
|
|
+
|
|
+@cindex special settings
|
|
+
|
|
+@table @samp
|
|
+@item min @var{n}
|
|
+@opindex min
|
|
+Set the minimum number of characters that will satisfy a read until
|
|
+the time value has expired, when @option{-icanon} is set.
|
|
+
|
|
+@item time @var{n}
|
|
+@opindex time
|
|
+Set the number of tenths of a second before reads time out if the minimum
|
|
+number of characters have not been read, when @option{-icanon} is set.
|
|
+
|
|
+@item ispeed @var{n}
|
|
+@opindex ispeed
|
|
+Set the input speed to @var{n}.
|
|
+
|
|
+@item ospeed @var{n}
|
|
+@opindex ospeed
|
|
+Set the output speed to @var{n}.
|
|
+
|
|
+@item rows @var{n}
|
|
+@opindex rows
|
|
+Tell the tty kernel driver that the terminal has @var{n} rows. Non-@acronym{POSIX}.
|
|
+
|
|
+@item cols @var{n}
|
|
+@itemx columns @var{n}
|
|
+@opindex cols
|
|
+@opindex columns
|
|
+Tell the kernel that the terminal has @var{n} columns. Non-@acronym{POSIX}.
|
|
+
|
|
+@item size
|
|
+@opindex size
|
|
+@vindex LINES
|
|
+@vindex COLUMNS
|
|
+Print the number of rows and columns that the kernel thinks the
|
|
+terminal has. (Systems that don't support rows and columns in the kernel
|
|
+typically use the environment variables @env{LINES} and @env{COLUMNS}
|
|
+instead; however, GNU @command{stty} does not know anything about them.)
|
|
+Non-@acronym{POSIX}.
|
|
+
|
|
+@item line @var{n}
|
|
+@opindex line
|
|
+Use line discipline @var{n}. Non-@acronym{POSIX}.
|
|
+
|
|
+@item speed
|
|
+@opindex speed
|
|
+Print the terminal speed.
|
|
+
|
|
+@item @var{n}
|
|
+@cindex baud rate, setting
|
|
+Set the input and output speeds to @var{n}. @var{n} can be one of: 0
|
|
+50 75 110 134 134.5 150 200 300 600 1200 1800 2400 4800 9600 19200
|
|
+38400 @code{exta} @code{extb}. @code{exta} is the same as 19200;
|
|
+@code{extb} is the same as 38400. Many systems, including GNU/Linux,
|
|
+support higher speeds. The @command{stty} command includes support
|
|
+for speeds of
|
|
+57600,
|
|
+115200,
|
|
+230400,
|
|
+460800,
|
|
+500000,
|
|
+576000,
|
|
+921600,
|
|
+1000000,
|
|
+1152000,
|
|
+1500000,
|
|
+2000000,
|
|
+2500000,
|
|
+3000000,
|
|
+3500000,
|
|
+or
|
|
+4000000 where the system supports these.
|
|
+0 hangs up the line if @option{-clocal} is set.
|
|
+@end table
|
|
+
|
|
+
|
|
+@node printenv invocation
|
|
+@section @command{printenv}: Print all or some environment variables
|
|
+
|
|
+@pindex printenv
|
|
+@cindex printing all or some environment variables
|
|
+@cindex environment variables, printing
|
|
+
|
|
+@command{printenv} prints environment variable values. Synopsis:
|
|
+
|
|
+@example
|
|
+printenv [@var{option}] [@var{variable}]@dots{}
|
|
+@end example
|
|
+
|
|
+If no @var{variable}s are specified, @command{printenv} prints the value of
|
|
+every environment variable. Otherwise, it prints the value of each
|
|
+@var{variable} that is set, and nothing for those that are not set.
|
|
+
|
|
+The only options are a lone @option{--help} or @option{--version}.
|
|
+@xref{Common options}.
|
|
+
|
|
+@cindex exit status of @command{printenv}
|
|
+Exit status:
|
|
+
|
|
+@display
|
|
+0 if all variables specified were found
|
|
+1 if at least one specified variable was not found
|
|
+2 if a write error occurred
|
|
+@end display
|
|
+
|
|
+
|
|
+@node tty invocation
|
|
+@section @command{tty}: Print file name of terminal on standard input
|
|
+
|
|
+@pindex tty
|
|
+@cindex print terminal file name
|
|
+@cindex terminal file name, printing
|
|
+
|
|
+@command{tty} prints the file name of the terminal connected to its standard
|
|
+input. It prints @samp{not a tty} if standard input is not a terminal.
|
|
+Synopsis:
|
|
+
|
|
+@example
|
|
+tty [@var{option}]@dots{}
|
|
+@end example
|
|
+
|
|
+The program accepts the following option. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -s
|
|
+@itemx --silent
|
|
+@itemx --quiet
|
|
+@opindex -s
|
|
+@opindex --silent
|
|
+@opindex --quiet
|
|
+Print nothing; only return an exit status.
|
|
+
|
|
+@end table
|
|
+
|
|
+@cindex exit status of @command{tty}
|
|
+Exit status:
|
|
+
|
|
+@display
|
|
+0 if standard input is a terminal
|
|
+1 if standard input is not a terminal
|
|
+2 if given incorrect arguments
|
|
+3 if a write error occurs
|
|
+@end display
|
|
+
|
|
+
|
|
+@node User information
|
|
+@chapter User information
|
|
+
|
|
+@cindex user information, commands for
|
|
+@cindex commands for printing user information
|
|
+
|
|
+This section describes commands that print user-related information:
|
|
+logins, groups, and so forth.
|
|
+
|
|
+@menu
|
|
+* 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.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node id invocation
|
|
+@section @command{id}: Print user identity
|
|
+
|
|
+@pindex id
|
|
+@cindex real user and group IDs, printing
|
|
+@cindex effective user and group IDs, printing
|
|
+@cindex printing real and effective user and group IDs
|
|
+
|
|
+@command{id} prints information about the given user, or the process
|
|
+running it if no user is specified. Synopsis:
|
|
+
|
|
+@example
|
|
+id [@var{option}]@dots{} [@var{username}]
|
|
+@end example
|
|
+
|
|
+@vindex POSIXLY_CORRECT
|
|
+By default, it prints the real user ID, real group ID, effective user ID
|
|
+if different from the real user ID, effective group ID if different from
|
|
+the real group ID, and supplemental group IDs.
|
|
+In addition, if SELinux
|
|
+is enabled and the @env{POSIXLY_CORRECT} environment variable is not set,
|
|
+then print @samp{context=@var{c}}, where @var{c} is the security context.
|
|
+
|
|
+Each of these numeric values is preceded by an identifying string and
|
|
+followed by the corresponding user or group name in parentheses.
|
|
+
|
|
+The options cause @command{id} to print only part of the above information.
|
|
+Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+@item -g
|
|
+@itemx --group
|
|
+@opindex -g
|
|
+@opindex --group
|
|
+Print only the group ID.
|
|
+
|
|
+@item -G
|
|
+@itemx --groups
|
|
+@opindex -G
|
|
+@opindex --groups
|
|
+Print only the group ID and the supplementary groups.
|
|
+
|
|
+@item -n
|
|
+@itemx --name
|
|
+@opindex -n
|
|
+@opindex --name
|
|
+Print the user or group name instead of the ID number. Requires
|
|
+@option{-u}, @option{-g}, or @option{-G}.
|
|
+
|
|
+@item -r
|
|
+@itemx --real
|
|
+@opindex -r
|
|
+@opindex --real
|
|
+Print the real, instead of effective, user or group ID. Requires
|
|
+@option{-u}, @option{-g}, or @option{-G}.
|
|
+
|
|
+@item -u
|
|
+@itemx --user
|
|
+@opindex -u
|
|
+@opindex --user
|
|
+Print only the user ID.
|
|
+
|
|
+@item -Z
|
|
+@itemx --context
|
|
+@opindex -Z
|
|
+@opindex --context
|
|
+@cindex SELinux
|
|
+@cindex security context
|
|
+Print only the security context of the current user.
|
|
+If SELinux is disabled then print a warning and
|
|
+set the exit status to 1.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+@macro primaryAndSupplementaryGroups{cmd,arg}
|
|
+Primary and supplementary groups for a process are normally inherited
|
|
+from its parent and are usually unchanged since login. This means
|
|
+that if you change the group database after logging in, @command{\cmd\}
|
|
+will not reflect your changes within your existing login session.
|
|
+Running @command{\cmd\} with a \arg\ causes the user and group
|
|
+database to be consulted afresh, and so will give a different result.
|
|
+@end macro
|
|
+@primaryAndSupplementaryGroups{id,user argument}
|
|
+
|
|
+@node logname invocation
|
|
+@section @command{logname}: Print current login name
|
|
+
|
|
+@pindex logname
|
|
+@cindex printing user's login name
|
|
+@cindex login name, printing
|
|
+@cindex user name, printing
|
|
+
|
|
+@flindex utmp
|
|
+@command{logname} prints the calling user's name, as found in a
|
|
+system-maintained file (often @file{/var/run/utmp} or
|
|
+@file{/etc/utmp}), and exits with a status of 0. If there is no entry
|
|
+for the calling process, @command{logname} prints
|
|
+an error message and exits with a status of 1.
|
|
+
|
|
+The only options are @option{--help} and @option{--version}. @xref{Common
|
|
+options}.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node whoami invocation
|
|
+@section @command{whoami}: Print effective user ID
|
|
+
|
|
+@pindex whoami
|
|
+@cindex effective user ID, printing
|
|
+@cindex printing the effective user ID
|
|
+
|
|
+@command{whoami} prints the user name associated with the current
|
|
+effective user ID. It is equivalent to the command @samp{id -un}.
|
|
+
|
|
+The only options are @option{--help} and @option{--version}. @xref{Common
|
|
+options}.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node groups invocation
|
|
+@section @command{groups}: Print group names a user is in
|
|
+
|
|
+@pindex groups
|
|
+@cindex printing groups a user is in
|
|
+@cindex supplementary groups, printing
|
|
+
|
|
+@command{groups} prints the names of the primary and any supplementary
|
|
+groups for each given @var{username}, or the current process if no names
|
|
+are given. If more than one name is given, the name of each user is
|
|
+printed before
|
|
+the list of that user's groups and the user name is separated from the
|
|
+group list by a colon. Synopsis:
|
|
+
|
|
+@example
|
|
+groups [@var{username}]@dots{}
|
|
+@end example
|
|
+
|
|
+The group lists are equivalent to the output of the command @samp{id -Gn}.
|
|
+
|
|
+@primaryAndSupplementaryGroups{groups,list of users}
|
|
+
|
|
+The only options are @option{--help} and @option{--version}. @xref{Common
|
|
+options}.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node users invocation
|
|
+@section @command{users}: Print login names of users currently logged in
|
|
+
|
|
+@pindex users
|
|
+@cindex printing current usernames
|
|
+@cindex usernames, printing current
|
|
+
|
|
+@cindex login sessions, printing users with
|
|
+@command{users} prints on a single line a blank-separated list of user
|
|
+names of users currently logged in to the current host. Each user name
|
|
+corresponds to a login session, so if a user has more than one login
|
|
+session, that user's name will appear the same number of times in the
|
|
+output. Synopsis:
|
|
+
|
|
+@example
|
|
+users [@var{file}]
|
|
+@end example
|
|
+
|
|
+@flindex utmp
|
|
+@flindex wtmp
|
|
+With no @var{file} argument, @command{users} extracts its information from
|
|
+a system-maintained file (often @file{/var/run/utmp} or
|
|
+@file{/etc/utmp}). If a file argument is given, @command{users} uses
|
|
+that file instead. A common choice is @file{/var/log/wtmp}.
|
|
+
|
|
+The only options are @option{--help} and @option{--version}. @xref{Common
|
|
+options}.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node who invocation
|
|
+@section @command{who}: Print who is currently logged in
|
|
+
|
|
+@pindex who
|
|
+@cindex printing current user information
|
|
+@cindex information, about current users
|
|
+
|
|
+@command{who} prints information about users who are currently logged on.
|
|
+Synopsis:
|
|
+
|
|
+@example
|
|
+@command{who} [@var{option}] [@var{file}] [am i]
|
|
+@end example
|
|
+
|
|
+@cindex terminal lines, currently used
|
|
+@cindex login time
|
|
+@cindex remote hostname
|
|
+If given no non-option arguments, @command{who} prints the following
|
|
+information for each user currently logged on: login name, terminal
|
|
+line, login time, and remote hostname or X display.
|
|
+
|
|
+@flindex utmp
|
|
+@flindex wtmp
|
|
+If given one non-option argument, @command{who} uses that instead of
|
|
+a default system-maintained file (often @file{/var/run/utmp} or
|
|
+@file{/etc/utmp}) as the name of the file containing the record of
|
|
+users logged on. @file{/var/log/wtmp} is commonly given as an argument
|
|
+to @command{who} to look at who has previously logged on.
|
|
+
|
|
+@opindex am i
|
|
+@opindex who am i
|
|
+If given two non-option arguments, @command{who} prints only the entry
|
|
+for the user running it (determined from its standard input), preceded
|
|
+by the hostname. Traditionally, the two arguments given are @samp{am
|
|
+i}, as in @samp{who am i}.
|
|
+
|
|
+@vindex TZ
|
|
+Time stamps are listed according to the time zone rules specified by
|
|
+the @env{TZ} environment variable, or by the system default rules if
|
|
+@env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone
|
|
+with @env{TZ}, libc, The GNU C Library Reference Manual}.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -a
|
|
+@itemx --all
|
|
+@opindex -a
|
|
+@opindex --all
|
|
+Same as @samp{-b -d --login -p -r -t -T -u}.
|
|
+
|
|
+@item -b
|
|
+@itemx --boot
|
|
+@opindex -b
|
|
+@opindex --boot
|
|
+Print the date and time of last system boot.
|
|
+
|
|
+@item -d
|
|
+@itemx --dead
|
|
+@opindex -d
|
|
+@opindex --dead
|
|
+Print information corresponding to dead processes.
|
|
+
|
|
+@item -H
|
|
+@itemx --heading
|
|
+@opindex -H
|
|
+@opindex --heading
|
|
+Print a line of column headings.
|
|
+
|
|
+@item -l
|
|
+@itemx --login
|
|
+@opindex -l
|
|
+@opindex --login
|
|
+List only the entries that correspond to processes via which the
|
|
+system is waiting for a user to login. The user name is always @samp{LOGIN}.
|
|
+
|
|
+@itemx --lookup
|
|
+@opindex --lookup
|
|
+Attempt to canonicalize hostnames found in utmp through a DNS lookup. This
|
|
+is not the default because it can cause significant delays on systems with
|
|
+automatic dial-up internet access.
|
|
+
|
|
+@item -m
|
|
+@opindex -m
|
|
+Same as @samp{who am i}.
|
|
+
|
|
+@item -p
|
|
+@itemx --process
|
|
+@opindex -p
|
|
+@opindex --process
|
|
+List active processes spawned by init.
|
|
+
|
|
+@item -q
|
|
+@itemx --count
|
|
+@opindex -q
|
|
+@opindex --count
|
|
+Print only the login names and the number of users logged on.
|
|
+Overrides all other options.
|
|
+
|
|
+@item -r
|
|
+@itemx --runlevel
|
|
+@opindex -r
|
|
+@opindex --runlevel
|
|
+Print the current (and maybe previous) run-level of the init process.
|
|
+
|
|
+@item -s
|
|
+@opindex -s
|
|
+Ignored; for compatibility with other versions of @command{who}.
|
|
+
|
|
+@item -t
|
|
+@itemx --time
|
|
+@opindex -t
|
|
+@opindex --time
|
|
+Print last system clock change.
|
|
+
|
|
+@itemx -u
|
|
+@opindex -u
|
|
+@cindex idle time
|
|
+After the login time, print the number of hours and minutes that the
|
|
+user has been idle. @samp{.} means the user was active in the last minute.
|
|
+@samp{old} means the user has been idle for more than 24 hours.
|
|
+
|
|
+@item -w
|
|
+@itemx -T
|
|
+@itemx --mesg
|
|
+@itemx --message
|
|
+@itemx --writable
|
|
+@opindex -w
|
|
+@opindex -T
|
|
+@opindex --mesg
|
|
+@opindex --message
|
|
+@opindex --writable
|
|
+@cindex message status
|
|
+@pindex write@r{, allowed}
|
|
+After each login name print a character indicating the user's message status:
|
|
+
|
|
+@display
|
|
+@samp{+} allowing @code{write} messages
|
|
+@samp{-} disallowing @code{write} messages
|
|
+@samp{?} cannot find terminal device
|
|
+@end display
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node System context
|
|
+@chapter System context
|
|
+
|
|
+@cindex system context
|
|
+@cindex context, system
|
|
+@cindex commands for system context
|
|
+
|
|
+This section describes commands that print or change system-wide
|
|
+information.
|
|
+
|
|
+@menu
|
|
+* date invocation:: Print or set system date and time.
|
|
+* arch invocation:: Print machine hardware name.
|
|
+* 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.
|
|
+@end menu
|
|
+
|
|
+@node date invocation
|
|
+@section @command{date}: Print or set system date and time
|
|
+
|
|
+@pindex date
|
|
+@cindex time, printing or setting
|
|
+@cindex printing the current time
|
|
+
|
|
+Synopses:
|
|
+
|
|
+@example
|
|
+date [@var{option}]@dots{} [+@var{format}]
|
|
+date [-u|--utc|--universal] @c this avoids a newline in the output
|
|
+[ MMDDhhmm[[CC]YY][.ss] ]
|
|
+@end example
|
|
+
|
|
+@vindex LC_TIME
|
|
+Invoking @command{date} with no @var{format} argument is equivalent to invoking
|
|
+it with a default format that depends on the @env{LC_TIME} locale category.
|
|
+In the default C locale, this format is @samp{'+%a %b %e %H:%M:%S %Z %Y'},
|
|
+so the output looks like @samp{Thu Mar @ 3 13:47:51 PST 2005}.
|
|
+
|
|
+@vindex TZ
|
|
+Normally, @command{date} uses the time zone rules indicated by the
|
|
+@env{TZ} environment variable, or the system default rules if @env{TZ}
|
|
+is not set. @xref{TZ Variable,, Specifying the Time Zone with
|
|
+@env{TZ}, libc, The GNU C Library Reference Manual}.
|
|
+
|
|
+@findex strftime @r{and @command{date}}
|
|
+@cindex time formats
|
|
+@cindex formatting times
|
|
+If given an argument that starts with a @samp{+}, @command{date} prints the
|
|
+current date and time (or the date and time specified by the
|
|
+@option{--date} option, see below) in the format defined by that argument,
|
|
+which is similar to that of the @code{strftime} function. Except for
|
|
+conversion specifiers, which start with @samp{%}, characters in the
|
|
+format string are printed unchanged. The conversion specifiers are
|
|
+described below.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+@menu
|
|
+* 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.
|
|
+@detailmenu
|
|
+* Date input formats:: Specifying date strings.
|
|
+@end detailmenu
|
|
+* Examples of date:: Examples.
|
|
+@end menu
|
|
+
|
|
+@node Time conversion specifiers
|
|
+@subsection Time conversion specifiers
|
|
+
|
|
+@cindex time conversion specifiers
|
|
+@cindex conversion specifiers, time
|
|
+
|
|
+@command{date} conversion specifiers related to times.
|
|
+
|
|
+@table @samp
|
|
+@item %H
|
|
+hour (@samp{00}@dots{}@samp{23})
|
|
+@item %I
|
|
+hour (@samp{01}@dots{}@samp{12})
|
|
+@item %k
|
|
+hour (@samp{ 0}@dots{}@samp{23}).
|
|
+This is a @acronym{GNU} extension.
|
|
+@item %l
|
|
+hour (@samp{ 1}@dots{}@samp{12}).
|
|
+This is a @acronym{GNU} extension.
|
|
+@item %M
|
|
+minute (@samp{00}@dots{}@samp{59})
|
|
+@item %N
|
|
+nanoseconds (@samp{000000000}@dots{}@samp{999999999}).
|
|
+This is a @acronym{GNU} extension.
|
|
+@item %p
|
|
+locale's equivalent of either @samp{AM} or @samp{PM};
|
|
+blank in many locales.
|
|
+Noon is treated as @samp{PM} and midnight as @samp{AM}.
|
|
+@item %P
|
|
+like @samp{%p}, except lower case.
|
|
+This is a @acronym{GNU} extension.
|
|
+@item %r
|
|
+locale's 12-hour clock time (e.g., @samp{11:11:04 PM})
|
|
+@item %R
|
|
+24-hour hour and minute. Same as @samp{%H:%M}.
|
|
+This is a @acronym{GNU} extension.
|
|
+@item %s
|
|
+@cindex epoch, seconds since
|
|
+@cindex seconds since the epoch
|
|
+@cindex beginning of time
|
|
+seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.
|
|
+Leap seconds are not counted unless leap second support is available.
|
|
+@xref{%s-examples}, for examples.
|
|
+This is a @acronym{GNU} extension.
|
|
+@item %S
|
|
+second (@samp{00}@dots{}@samp{60}).
|
|
+This may be @samp{60} if leap seconds are supported.
|
|
+@item %T
|
|
+24-hour hour, minute, and second. Same as @samp{%H:%M:%S}.
|
|
+@item %X
|
|
+locale's time representation (e.g., @samp{23:13:48})
|
|
+@item %z
|
|
+@w{@acronym{RFC} 2822/@acronym{ISO} 8601} style numeric time zone
|
|
+(e.g., @samp{-0600} or @samp{+0530}), or nothing if no
|
|
+time zone is determinable. This value reflects the numeric time zone
|
|
+appropriate for the current time, using the time zone rules specified
|
|
+by the @env{TZ} environment variable.
|
|
+The time (and optionally, the time zone rules) can be overridden
|
|
+by the @option{--date} option.
|
|
+This is a @acronym{GNU} extension.
|
|
+@item %:z
|
|
+@w{@acronym{RFC} 3339/@acronym{ISO} 8601} style numeric time zone with
|
|
+@samp{:} (e.g., @samp{-06:00} or @samp{+05:30}), or nothing if no time
|
|
+zone is determinable.
|
|
+This is a @acronym{GNU} extension.
|
|
+@item %::z
|
|
+Numeric time zone to the nearest second with @samp{:} (e.g.,
|
|
+@samp{-06:00:00} or @samp{+05:30:00}), or nothing if no time zone is
|
|
+determinable.
|
|
+This is a @acronym{GNU} extension.
|
|
+@item %:::z
|
|
+Numeric time zone with @samp{:} using the minimum necessary precision
|
|
+(e.g., @samp{-06}, @samp{+05:30}, or @samp{-04:56:02}), or nothing if
|
|
+no time zone is determinable.
|
|
+This is a @acronym{GNU} extension.
|
|
+@item %Z
|
|
+alphabetic time zone abbreviation (e.g., @samp{EDT}), or nothing if no
|
|
+time zone is determinable. See @samp{%z} for how it is determined.
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Date conversion specifiers
|
|
+@subsection Date conversion specifiers
|
|
+
|
|
+@cindex date conversion specifiers
|
|
+@cindex conversion specifiers, date
|
|
+
|
|
+@command{date} conversion specifiers related to dates.
|
|
+
|
|
+@table @samp
|
|
+@item %a
|
|
+locale's abbreviated weekday name (e.g., @samp{Sun})
|
|
+@item %A
|
|
+locale's full weekday name, variable length (e.g., @samp{Sunday})
|
|
+@item %b
|
|
+locale's abbreviated month name (e.g., @samp{Jan})
|
|
+@item %B
|
|
+locale's full month name, variable length (e.g., @samp{January})
|
|
+@item %c
|
|
+locale's date and time (e.g., @samp{Thu Mar @ 3 23:05:25 2005})
|
|
+@item %C
|
|
+century. This is like @samp{%Y}, except the last two digits are omitted.
|
|
+For example, it is @samp{20} if @samp{%Y} is @samp{2000},
|
|
+and is @samp{-0} if @samp{%Y} is @samp{-001}.
|
|
+It is normally at least two characters, but it may be more.
|
|
+@item %d
|
|
+day of month (e.g., @samp{01})
|
|
+@item %D
|
|
+date; same as @samp{%m/%d/%y}
|
|
+@item %e
|
|
+day of month, space padded; same as @samp{%_d}
|
|
+@item %F
|
|
+full date in @acronym{ISO} 8601 format; same as @samp{%Y-%m-%d}.
|
|
+This is a good choice for a date format, as it is standard and
|
|
+is easy to sort in the usual case where years are in the range
|
|
+0000@dots{}9999.
|
|
+This is a @acronym{GNU} extension.
|
|
+@item %g
|
|
+year corresponding to the @acronym{ISO} week number, but without the century
|
|
+(range @samp{00} through @samp{99}). This has the same format and value
|
|
+as @samp{%y}, except that if the @acronym{ISO} week number (see
|
|
+@samp{%V}) belongs
|
|
+to the previous or next year, that year is used instead.
|
|
+This is a @acronym{GNU} extension.
|
|
+@item %G
|
|
+year corresponding to the @acronym{ISO} week number. This has the
|
|
+same format and value as @samp{%Y}, except that if the @acronym{ISO}
|
|
+week number (see
|
|
+@samp{%V}) belongs to the previous or next year, that year is used
|
|
+instead.
|
|
+It is normally useful only if @samp{%V} is also used;
|
|
+for example, the format @samp{%G-%m-%d} is probably a mistake,
|
|
+since it combines the ISO week number year with the conventional month and day.
|
|
+This is a @acronym{GNU} extension.
|
|
+@item %h
|
|
+same as @samp{%b}
|
|
+@item %j
|
|
+day of year (@samp{001}@dots{}@samp{366})
|
|
+@item %m
|
|
+month (@samp{01}@dots{}@samp{12})
|
|
+@item %u
|
|
+day of week (@samp{1}@dots{}@samp{7}) with @samp{1} corresponding to Monday
|
|
+@item %U
|
|
+week number of year, with Sunday as the first day of the week
|
|
+(@samp{00}@dots{}@samp{53}).
|
|
+Days in a new year preceding the first Sunday are in week zero.
|
|
+@item %V
|
|
+@acronym{ISO} week number, that is, the
|
|
+week number of year, with Monday as the first day of the week
|
|
+(@samp{01}@dots{}@samp{53}).
|
|
+If the week containing January 1 has four or more days in
|
|
+the new year, then it is considered week 1; otherwise, it is week 53 of
|
|
+the previous year, and the next week is week 1. (See the @acronym{ISO} 8601
|
|
+standard.)
|
|
+@item %w
|
|
+day of week (@samp{0}@dots{}@samp{6}) with 0 corresponding to Sunday
|
|
+@item %W
|
|
+week number of year, with Monday as first day of week
|
|
+(@samp{00}@dots{}@samp{53}).
|
|
+Days in a new year preceding the first Monday are in week zero.
|
|
+@item %x
|
|
+locale's date representation (e.g., @samp{12/31/99})
|
|
+@item %y
|
|
+last two digits of year (@samp{00}@dots{}@samp{99})
|
|
+@item %Y
|
|
+year. This is normally at least four characters, but it may be more.
|
|
+Year @samp{0000} precedes year @samp{0001}, and year @samp{-001}
|
|
+precedes year @samp{0000}.
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Literal conversion specifiers
|
|
+@subsection Literal conversion specifiers
|
|
+
|
|
+@cindex literal conversion specifiers
|
|
+@cindex conversion specifiers, literal
|
|
+
|
|
+@command{date} conversion specifiers that produce literal strings.
|
|
+
|
|
+@table @samp
|
|
+@item %%
|
|
+a literal %
|
|
+@item %n
|
|
+a newline
|
|
+@item %t
|
|
+a horizontal tab
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Padding and other flags
|
|
+@subsection Padding and other flags
|
|
+
|
|
+@cindex numeric field padding
|
|
+@cindex padding of numeric fields
|
|
+@cindex fields, padding numeric
|
|
+
|
|
+Unless otherwise specified, @command{date} normally pads numeric fields
|
|
+with zeros, so that, for
|
|
+example, numeric months are always output as two digits.
|
|
+Seconds since the epoch are not padded, though,
|
|
+since there is no natural width for them.
|
|
+
|
|
+As a @acronym{GNU} extension, @command{date} recognizes any of the
|
|
+following optional flags after the @samp{%}:
|
|
+
|
|
+@table @samp
|
|
+@item -
|
|
+(hyphen) Do not pad the field; useful if the output is intended for
|
|
+human consumption.
|
|
+@item _
|
|
+(underscore) Pad with spaces; useful if you need a fixed
|
|
+number of characters in the output, but zeros are too distracting.
|
|
+@item 0
|
|
+(zero) Pad with zeros even if the conversion specifier
|
|
+would normally pad with spaces.
|
|
+@item ^
|
|
+Use upper case characters if possible.
|
|
+@item #
|
|
+Use opposite case characters if possible.
|
|
+A field that is normally upper case becomes lower case, and vice versa.
|
|
+@end table
|
|
+
|
|
+@noindent
|
|
+Here are some examples of padding:
|
|
+
|
|
+@example
|
|
+date +%d/%m -d "Feb 1"
|
|
+@result{} 01/02
|
|
+date +%-d/%-m -d "Feb 1"
|
|
+@result{} 1/2
|
|
+date +%_d/%_m -d "Feb 1"
|
|
+@result{} 1/ 2
|
|
+@end example
|
|
+
|
|
+As a @acronym{GNU} extension, you can specify the field width
|
|
+(after any flag, if present) as a decimal number. If the natural size of the
|
|
+output of the field has less than the specified number of characters,
|
|
+the result is written right adjusted and padded to the given
|
|
+size. For example, @samp{%9B} prints the right adjusted month name in
|
|
+a field of width 9.
|
|
+
|
|
+An optional modifier can follow the optional flag and width
|
|
+specification. The modifiers are:
|
|
+
|
|
+@table @samp
|
|
+@item E
|
|
+Use the locale's alternate representation for date and time. This
|
|
+modifier applies to the @samp{%c}, @samp{%C}, @samp{%x}, @samp{%X},
|
|
+@samp{%y} and @samp{%Y} conversion specifiers. In a Japanese locale, for
|
|
+example, @samp{%Ex} might yield a date format based on the Japanese
|
|
+Emperors' reigns.
|
|
+
|
|
+@item O
|
|
+Use the locale's alternate numeric symbols for numbers. This modifier
|
|
+applies only to numeric conversion specifiers.
|
|
+@end table
|
|
+
|
|
+If the format supports the modifier but no alternate representation
|
|
+is available, it is ignored.
|
|
+
|
|
+
|
|
+@node Setting the time
|
|
+@subsection Setting the time
|
|
+
|
|
+@cindex setting the time
|
|
+@cindex time setting
|
|
+@cindex appropriate privileges
|
|
+
|
|
+If given an argument that does not start with @samp{+}, @command{date} sets
|
|
+the system clock to the date and time specified by that argument (as
|
|
+described below). You must have appropriate privileges to set the
|
|
+system clock. The @option{--date} and @option{--set} options may not be
|
|
+used with such an argument. The @option{--universal} option may be used
|
|
+with such an argument to indicate that the specified date and time are
|
|
+relative to Coordinated Universal Time rather than to the local time
|
|
+zone.
|
|
+
|
|
+The argument must consist entirely of digits, which have the following
|
|
+meaning:
|
|
+
|
|
+@table @samp
|
|
+@item MM
|
|
+month
|
|
+@item DD
|
|
+day within month
|
|
+@item hh
|
|
+hour
|
|
+@item mm
|
|
+minute
|
|
+@item CC
|
|
+first two digits of year (optional)
|
|
+@item YY
|
|
+last two digits of year (optional)
|
|
+@item ss
|
|
+second (optional)
|
|
+@end table
|
|
+
|
|
+The @option{--set} option also sets the system clock; see the next section.
|
|
+
|
|
+
|
|
+@node Options for date
|
|
+@subsection Options for @command{date}
|
|
+
|
|
+@cindex @command{date} options
|
|
+@cindex options for @command{date}
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -d @var{datestr}
|
|
+@itemx --date=@var{datestr}
|
|
+@opindex -d
|
|
+@opindex --date
|
|
+@cindex parsing date strings
|
|
+@cindex date strings, parsing
|
|
+@cindex arbitrary date strings, parsing
|
|
+@opindex yesterday
|
|
+@opindex tomorrow
|
|
+@opindex next @var{day}
|
|
+@opindex last @var{day}
|
|
+Display the date and time specified in @var{datestr} instead of the
|
|
+current date and time. @var{datestr} can be in almost any common
|
|
+format. It can contain month names, time zones, @samp{am} and @samp{pm},
|
|
+@samp{yesterday}, etc. For example, @option{--date="2004-02-27
|
|
+14:19:13.489392193 +0530"} specifies the instant of time that is
|
|
+489,392,193 nanoseconds after February 27, 2004 at 2:19:13 PM in a
|
|
+time zone that is 5 hours and 30 minutes east of @acronym{UTC}.@*
|
|
+Note: input currently must be in locale independent format. E.g., the
|
|
+LC_TIME=C below is needed to print back the correct date in many locales:
|
|
+@example
|
|
+date -d "$(LC_TIME=C date)"
|
|
+@end example
|
|
+@xref{Date input formats}.
|
|
+
|
|
+@item -f @var{datefile}
|
|
+@itemx --file=@var{datefile}
|
|
+@opindex -f
|
|
+@opindex --file
|
|
+Parse each line in @var{datefile} as with @option{-d} and display the
|
|
+resulting date and time. If @var{datefile} is @samp{-}, use standard
|
|
+input. This is useful when you have many dates to process, because the
|
|
+system overhead of starting up the @command{date} executable many times can
|
|
+be considerable.
|
|
+
|
|
+@item -r @var{file}
|
|
+@itemx --reference=@var{file}
|
|
+@opindex -r
|
|
+@opindex --reference
|
|
+Display the date and time of the last modification of @var{file},
|
|
+instead of the current date and time.
|
|
+
|
|
+@item -R
|
|
+@itemx --rfc-822
|
|
+@itemx --rfc-2822
|
|
+@opindex -R
|
|
+@opindex --rfc-822
|
|
+@opindex --rfc-2822
|
|
+Display the date and time using the format @samp{%a, %d %b %Y %H:%M:%S
|
|
+%z}, evaluated in the C locale so abbreviations are always in English.
|
|
+For example:
|
|
+
|
|
+@example
|
|
+Fri, 09 Sep 2005 13:51:39 -0700
|
|
+@end example
|
|
+
|
|
+This format conforms to
|
|
+@uref{ftp://ftp.rfc-editor.org/in-notes/rfc2822.txt, Internet
|
|
+@acronym{RFCs} 2822} and
|
|
+@uref{ftp://ftp.rfc-editor.org/in-notes/rfc822.txt, 822}, the
|
|
+current and previous standards for Internet email.
|
|
+
|
|
+@item --rfc-3339=@var{timespec}
|
|
+@opindex --rfc-3339=@var{timespec}
|
|
+Display the date using a format specified by
|
|
+@uref{ftp://ftp.rfc-editor.org/in-notes/rfc3339.txt, Internet
|
|
+@acronym{RFC} 3339}. This is a subset of the @acronym{ISO} 8601
|
|
+format, except that it also permits applications to use a space rather
|
|
+than a @samp{T} to separate dates from times. Unlike the other
|
|
+standard formats, @acronym{RFC} 3339 format is always suitable as
|
|
+input for the @option{--date} (@option{-d}) and @option{--file}
|
|
+(@option{-f}) options, regardless of the current locale.
|
|
+
|
|
+The argument @var{timespec} specifies how much of the time to include.
|
|
+It can be one of the following:
|
|
+
|
|
+@table @samp
|
|
+@item date
|
|
+Print just the full-date, e.g., @samp{2005-09-14}.
|
|
+This is equivalent to the format @samp{%Y-%m-%d}.
|
|
+
|
|
+@item seconds
|
|
+Print the full-date and full-time separated by a space, e.g.,
|
|
+@samp{2005-09-14 00:56:06+05:30}. The output ends with a numeric
|
|
+time-offset; here the @samp{+05:30} means that local time is five
|
|
+hours and thirty minutes east of @acronym{UTC}. This is equivalent to
|
|
+the format @samp{%Y-%m-%d %H:%M:%S%:z}.
|
|
+
|
|
+@item ns
|
|
+Like @samp{seconds}, but also print nanoseconds, e.g.,
|
|
+@samp{2005-09-14 00:56:06.998458565+05:30}.
|
|
+This is equivalent to the format @samp{%Y-%m-%d %H:%M:%S.%N%:z}.
|
|
+
|
|
+@end table
|
|
+
|
|
+@item -s @var{datestr}
|
|
+@itemx --set=@var{datestr}
|
|
+@opindex -s
|
|
+@opindex --set
|
|
+Set the date and time to @var{datestr}. See @option{-d} above.
|
|
+
|
|
+@item -u
|
|
+@itemx --utc
|
|
+@itemx --universal
|
|
+@opindex -u
|
|
+@opindex --utc
|
|
+@opindex --universal
|
|
+@cindex Coordinated Universal Time
|
|
+@cindex UTC
|
|
+@cindex Greenwich Mean Time
|
|
+@cindex GMT
|
|
+@vindex TZ
|
|
+Use Coordinated Universal Time (@acronym{UTC}) by operating as if the
|
|
+@env{TZ} environment variable were set to the string @samp{UTC0}.
|
|
+Coordinated
|
|
+Universal Time is often called ``Greenwich Mean Time'' (@sc{gmt}) for
|
|
+historical reasons.
|
|
+@end table
|
|
+
|
|
+
|
|
+@node Examples of date
|
|
+@subsection Examples of @command{date}
|
|
+
|
|
+@cindex examples of @command{date}
|
|
+
|
|
+Here are a few examples. Also see the documentation for the @option{-d}
|
|
+option in the previous section.
|
|
+
|
|
+@itemize @bullet
|
|
+
|
|
+@item
|
|
+To print the date of the day before yesterday:
|
|
+
|
|
+@example
|
|
+date --date='2 days ago'
|
|
+@end example
|
|
+
|
|
+@item
|
|
+To print the date of the day three months and one day hence:
|
|
+
|
|
+@example
|
|
+date --date='3 months 1 day'
|
|
+@end example
|
|
+
|
|
+@item
|
|
+To print the day of year of Christmas in the current year:
|
|
+
|
|
+@example
|
|
+date --date='25 Dec' +%j
|
|
+@end example
|
|
+
|
|
+@item
|
|
+To print the current full month name and the day of the month:
|
|
+
|
|
+@example
|
|
+date '+%B %d'
|
|
+@end example
|
|
+
|
|
+But this may not be what you want because for the first nine days of
|
|
+the month, the @samp{%d} expands to a zero-padded two-digit field,
|
|
+for example @samp{date -d 1may '+%B %d'} will print @samp{May 01}.
|
|
+
|
|
+@item
|
|
+To print a date without the leading zero for one-digit days
|
|
+of the month, you can use the (@acronym{GNU} extension)
|
|
+@samp{-} flag to suppress
|
|
+the padding altogether:
|
|
+
|
|
+@example
|
|
+date -d 1may '+%B %-d
|
|
+@end example
|
|
+
|
|
+@item
|
|
+To print the current date and time in the format required by many
|
|
+non-@acronym{GNU} versions of @command{date} when setting the system clock:
|
|
+
|
|
+@example
|
|
+date +%m%d%H%M%Y.%S
|
|
+@end example
|
|
+
|
|
+@item
|
|
+To set the system clock forward by two minutes:
|
|
+
|
|
+@example
|
|
+date --set='+2 minutes'
|
|
+@end example
|
|
+
|
|
+@item
|
|
+To print the date in @acronym{RFC} 2822 format,
|
|
+use @samp{date --rfc-2822}. Here is some example output:
|
|
+
|
|
+@example
|
|
+Fri, 09 Sep 2005 13:51:39 -0700
|
|
+@end example
|
|
+
|
|
+@anchor{%s-examples}
|
|
+@item
|
|
+To convert a date string to the number of seconds since the epoch
|
|
+(which is 1970-01-01 00:00:00 UTC), use the @option{--date} option with
|
|
+the @samp{%s} format. That can be useful in sorting and/or graphing
|
|
+and/or comparing data by date. The following command outputs the
|
|
+number of the seconds since the epoch for the time two minutes after the
|
|
+epoch:
|
|
+
|
|
+@example
|
|
+date --date='1970-01-01 00:02:00 +0000' +%s
|
|
+120
|
|
+@end example
|
|
+
|
|
+If you do not specify time zone information in the date string,
|
|
+@command{date} uses your computer's idea of the time zone when
|
|
+interpreting the string. For example, if your computer's time zone is
|
|
+that of Cambridge, Massachusetts, which was then 5 hours (i.e., 18,000
|
|
+seconds) behind UTC:
|
|
+
|
|
+@example
|
|
+# local time zone used
|
|
+date --date='1970-01-01 00:02:00' +%s
|
|
+18120
|
|
+@end example
|
|
+
|
|
+@item
|
|
+If you're sorting or graphing dated data, your raw date values may be
|
|
+represented as seconds since the epoch. But few people can look at
|
|
+the date @samp{946684800} and casually note ``Oh, that's the first second
|
|
+of the year 2000 in Greenwich, England.''
|
|
+
|
|
+@example
|
|
+date --date='2000-01-01 UTC' +%s
|
|
+946684800
|
|
+@end example
|
|
+
|
|
+An alternative is to use the @option{--utc} (@option{-u}) option.
|
|
+Then you may omit @samp{UTC} from the date string. Although this
|
|
+produces the same result for @samp{%s} and many other format sequences,
|
|
+with a time zone offset different from zero, it would give a different
|
|
+result for zone-dependent formats like @samp{%z}.
|
|
+
|
|
+@example
|
|
+date -u --date=2000-01-01 +%s
|
|
+946684800
|
|
+@end example
|
|
+
|
|
+To convert such an unwieldy number of seconds back to
|
|
+a more readable form, use a command like this:
|
|
+
|
|
+@smallexample
|
|
+# local time zone used
|
|
+date -d '1970-01-01 UTC 946684800 seconds' +"%Y-%m-%d %T %z"
|
|
+1999-12-31 19:00:00 -0500
|
|
+@end smallexample
|
|
+
|
|
+Or if you do not mind depending on the @samp{@@} feature present since
|
|
+coreutils 5.3.0, you could shorten this to:
|
|
+
|
|
+@smallexample
|
|
+date -d @@946684800 +"%F %T %z"
|
|
+1999-12-31 19:00:00 -0500
|
|
+@end smallexample
|
|
+
|
|
+Often it is better to output UTC-relative date and time:
|
|
+
|
|
+@smallexample
|
|
+date -u -d '1970-01-01 946684800 seconds' +"%Y-%m-%d %T %z"
|
|
+2000-01-01 00:00:00 +0000
|
|
+@end smallexample
|
|
+
|
|
+@end itemize
|
|
+
|
|
+
|
|
+@node arch invocation
|
|
+@section @command{arch}: Print machine hardware name
|
|
+
|
|
+@pindex arch
|
|
+@cindex print machine hardware name
|
|
+@cindex system information, printing
|
|
+
|
|
+@command{arch} prints the machine hardware name,
|
|
+and is equivalent to @samp{uname -m}.
|
|
+Synopsis:
|
|
+
|
|
+@example
|
|
+arch [@var{option}]
|
|
+@end example
|
|
+
|
|
+The program accepts the @ref{Common options} only.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node uname invocation
|
|
+@section @command{uname}: Print system information
|
|
+
|
|
+@pindex uname
|
|
+@cindex print system information
|
|
+@cindex system information, printing
|
|
+
|
|
+@command{uname} prints information about the machine and operating system
|
|
+it is run on. If no options are given, @command{uname} acts as if the
|
|
+@option{-s} option were given. Synopsis:
|
|
+
|
|
+@example
|
|
+uname [@var{option}]@dots{}
|
|
+@end example
|
|
+
|
|
+If multiple options or @option{-a} are given, the selected information is
|
|
+printed in this order:
|
|
+
|
|
+@example
|
|
+@var{kernel-name} @var{nodename} @var{kernel-release} @var{kernel-version}
|
|
+@var{machine} @var{processor} @var{hardware-platform} @var{operating-system}
|
|
+@end example
|
|
+
|
|
+The information may contain internal spaces, so such output cannot be
|
|
+parsed reliably. In the following example, @var{release} is
|
|
+@samp{2.2.18ss.e820-bda652a #4 SMP Tue Jun 5 11:24:08 PDT 2001}:
|
|
+
|
|
+@smallexample
|
|
+uname -a
|
|
+@result{} Linux dum 2.2.18 #4 SMP Tue Jun 5 11:24:08 PDT 2001 i686 unknown unknown GNU/Linux
|
|
+@end smallexample
|
|
+
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -a
|
|
+@itemx --all
|
|
+@opindex -a
|
|
+@opindex --all
|
|
+Print all of the below information, except omit the processor type
|
|
+and the hardware platform name if they are unknown.
|
|
+
|
|
+@item -i
|
|
+@itemx --hardware-platform
|
|
+@opindex -i
|
|
+@opindex --hardware-platform
|
|
+@cindex implementation, hardware
|
|
+@cindex hardware platform
|
|
+@cindex platform, hardware
|
|
+Print the hardware platform name
|
|
+(sometimes called the hardware implementation).
|
|
+Print @samp{unknown} if the kernel does not make this information
|
|
+easily available, as is the case with Linux kernels.
|
|
+
|
|
+@item -m
|
|
+@itemx --machine
|
|
+@opindex -m
|
|
+@opindex --machine
|
|
+@cindex machine type
|
|
+@cindex hardware class
|
|
+@cindex hardware type
|
|
+Print the machine hardware name (sometimes called the hardware class
|
|
+or hardware type).
|
|
+
|
|
+@item -n
|
|
+@itemx --nodename
|
|
+@opindex -n
|
|
+@opindex --nodename
|
|
+@cindex hostname
|
|
+@cindex node name
|
|
+@cindex network node name
|
|
+Print the network node hostname.
|
|
+
|
|
+@item -p
|
|
+@itemx --processor
|
|
+@opindex -p
|
|
+@opindex --processor
|
|
+@cindex host processor type
|
|
+Print the processor type (sometimes called the instruction set
|
|
+architecture or ISA).
|
|
+Print @samp{unknown} if the kernel does not make this information
|
|
+easily available, as is the case with Linux kernels.
|
|
+
|
|
+@item -o
|
|
+@itemx --operating-system
|
|
+@opindex -o
|
|
+@opindex --operating-system
|
|
+@cindex operating system name
|
|
+Print the name of the operating system.
|
|
+
|
|
+@item -r
|
|
+@itemx --kernel-release
|
|
+@opindex -r
|
|
+@opindex --kernel-release
|
|
+@cindex kernel release
|
|
+@cindex release of kernel
|
|
+Print the kernel release.
|
|
+
|
|
+@item -s
|
|
+@itemx --kernel-name
|
|
+@opindex -s
|
|
+@opindex --kernel-name
|
|
+@cindex kernel name
|
|
+@cindex name of kernel
|
|
+Print the kernel name.
|
|
+@acronym{POSIX} 1003.1-2001 (@pxref{Standards conformance}) calls this
|
|
+``the implementation of the operating system'', because the
|
|
+@acronym{POSIX} specification itself has no notion of ``kernel''.
|
|
+The kernel name might be the same as the operating system name printed
|
|
+by the @option{-o} or @option{--operating-system} option, but it might
|
|
+differ. Some operating systems (e.g., FreeBSD, HP-UX) have the same
|
|
+name as their underlying kernels; others (e.g., GNU/Linux, Solaris)
|
|
+do not.
|
|
+
|
|
+@item -v
|
|
+@itemx --kernel-version
|
|
+@opindex -v
|
|
+@opindex --kernel-version
|
|
+@cindex kernel version
|
|
+@cindex version of kernel
|
|
+Print the kernel version.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node hostname invocation
|
|
+@section @command{hostname}: Print or set system name
|
|
+
|
|
+@pindex hostname
|
|
+@cindex setting the hostname
|
|
+@cindex printing the hostname
|
|
+@cindex system name, printing
|
|
+@cindex appropriate privileges
|
|
+
|
|
+With no arguments, @command{hostname} prints the name of the current host
|
|
+system. With one argument, it sets the current host name to the
|
|
+specified string. You must have appropriate privileges to set the host
|
|
+name. Synopsis:
|
|
+
|
|
+@example
|
|
+hostname [@var{name}]
|
|
+@end example
|
|
+
|
|
+The only options are @option{--help} and @option{--version}. @xref{Common
|
|
+options}.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node hostid invocation
|
|
+@section @command{hostid}: Print numeric host identifier
|
|
+
|
|
+@pindex hostid
|
|
+@cindex printing the host identifier
|
|
+
|
|
+@command{hostid} prints the numeric identifier of the current host
|
|
+in hexadecimal. This command accepts no arguments.
|
|
+The only options are @option{--help} and @option{--version}.
|
|
+@xref{Common options}.
|
|
+
|
|
+For example, here's what it prints on one system I use:
|
|
+
|
|
+@example
|
|
+$ hostid
|
|
+1bac013d
|
|
+@end example
|
|
+
|
|
+On that system, the 32-bit quantity happens to be closely
|
|
+related to the system's Internet address, but that isn't always
|
|
+the case.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+@node uptime invocation
|
|
+@section @command{uptime}: Print system uptime and load
|
|
+
|
|
+@pindex uptime
|
|
+@cindex printing the system uptime and load
|
|
+
|
|
+@command{uptime} prints the current time, the system's uptime, the
|
|
+number of logged-in users and the current load average.
|
|
+
|
|
+If an argument is specified, it is used as the file to be read
|
|
+to discover how many users are logged in. If no argument is
|
|
+specified, a system default is used (@command{uptime --help} indicates
|
|
+the default setting).
|
|
+
|
|
+The only options are @option{--help} and @option{--version}.
|
|
+@xref{Common options}.
|
|
+
|
|
+For example, here's what it prints right now on one system I use:
|
|
+
|
|
+@example
|
|
+$ uptime
|
|
+ 14:07 up 3:35, 3 users, load average: 1.39, 1.15, 1.04
|
|
+@end example
|
|
+
|
|
+The precise method of calculation of load average varies somewhat
|
|
+between systems. Some systems calculate it as the average number of
|
|
+runnable processes over the last 1, 5 and 15 minutes, but some systems
|
|
+also include processes in the uninterruptible sleep state (that is,
|
|
+those processes which are waiting for disk I/O). The Linux kernel
|
|
+includes uninterruptible processes.
|
|
+
|
|
+@node SELinux context
|
|
+@chapter SELinux context
|
|
+
|
|
+@cindex SELinux context
|
|
+@cindex SELinux, context
|
|
+@cindex commands for SELinux context
|
|
+
|
|
+This section describes commands for operations with SELinux
|
|
+contexts.
|
|
+
|
|
+@menu
|
|
+* chcon invocation:: Change SELinux context of file
|
|
+* runcon invocation:: Run a command in specified SELinux context
|
|
+@end menu
|
|
+
|
|
+@node chcon invocation
|
|
+@section @command{chcon}: Change SELinux context of file
|
|
+
|
|
+@pindex chcon
|
|
+@cindex changing security context
|
|
+@cindex change SELinux context
|
|
+
|
|
+@command{chcon} changes the SELinux security context of the selected files.
|
|
+Synopses:
|
|
+
|
|
+@smallexample
|
|
+chcon [@var{option}]@dots{} @var{context} @var{file}@dots{}
|
|
+chcon [@var{option}]@dots{} [-u @var{user}] [-r @var{role}] [-l @var{range}] [-t @var{type}] @var{file}@dots{}
|
|
+chcon [@var{option}]@dots{} --reference=@var{rfile} @var{file}@dots{}
|
|
+@end smallexample
|
|
+
|
|
+Change the SELinux security context of each @var{file} to @var{context}.
|
|
+With @option{--reference}, change the security context of each @var{file}
|
|
+to that of @var{rfile}.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -h
|
|
+@itemx --no-dereference
|
|
+@opindex -h
|
|
+@opindex --no-dereference
|
|
+@cindex no dereference
|
|
+Affect symbolic links instead of any referenced file.
|
|
+
|
|
+@item --reference=@var{rfile}
|
|
+@opindex --reference
|
|
+@cindex reference file
|
|
+Use @var{rfile}'s security context rather than specifying a @var{context} value.
|
|
+
|
|
+@item -R
|
|
+@itemx --recursive
|
|
+@opindex -R
|
|
+@opindex --recursive
|
|
+Operate on files and directories recursively.
|
|
+
|
|
+@choptH
|
|
+@xref{Traversing symlinks}.
|
|
+
|
|
+@choptL
|
|
+@xref{Traversing symlinks}.
|
|
+
|
|
+@choptP
|
|
+@xref{Traversing symlinks}.
|
|
+
|
|
+@item -v
|
|
+@itemx --verbose
|
|
+@opindex -v
|
|
+@opindex --verbose
|
|
+@cindex diagnostic
|
|
+Output a diagnostic for every file processed.
|
|
+
|
|
+@item -u @var{user}
|
|
+@itemx --user=@var{user}
|
|
+@opindex -u
|
|
+@opindex --user
|
|
+Set user @var{user} in the target security context.
|
|
+
|
|
+@item -r @var{role}
|
|
+@itemx --role=@var{role}
|
|
+@opindex -r
|
|
+@opindex --role
|
|
+Set role @var{role} in the target security context.
|
|
+
|
|
+@item -t @var{type}
|
|
+@itemx --type=@var{type}
|
|
+@opindex -t
|
|
+@opindex --type
|
|
+Set type @var{type} in the target security context.
|
|
+
|
|
+@item -l @var{range}
|
|
+@itemx --range=@var{range}
|
|
+@opindex -l
|
|
+@opindex --range
|
|
+Set range @var{range} in the target security context.
|
|
+
|
|
+@end table
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+@node runcon invocation
|
|
+@section @command{runcon}: Run a command in specified SELinux context
|
|
+
|
|
+@pindex runcon
|
|
+@cindex run with security context
|
|
+
|
|
+
|
|
+@command{runcon} runs file in specified SELinux security context.
|
|
+
|
|
+Synopses:
|
|
+@smallexample
|
|
+runcon @var{context} @var{command} [@var{args}]
|
|
+runcon [ -c ] [-u @var{user}] [-r @var{role}] [-t @var{type}] [-l @var{range}] @var{command} [@var{args}]
|
|
+@end smallexample
|
|
+
|
|
+Run @var{command} with completely-specified @var{context}, or with
|
|
+current or transitioned security context modified by one or more of @var{level},
|
|
+@var{role}, @var{type} and @var{user}.
|
|
+
|
|
+If none of @option{-c}, @option{-t}, @option{-u}, @option{-r}, or @option{-l}
|
|
+is specified, the first argument is used as the complete context.
|
|
+Any additional arguments after @var{command}
|
|
+are interpreted as arguments to the command.
|
|
+
|
|
+With neither @var{context} nor @var{command}, print the current security context.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -c
|
|
+@itemx --compute
|
|
+@opindex -c
|
|
+@opindex --compute
|
|
+Compute process transition context before modifying.
|
|
+
|
|
+@item -u @var{user}
|
|
+@itemx --user=@var{user}
|
|
+@opindex -u
|
|
+@opindex --user
|
|
+Set user @var{user} in the target security context.
|
|
+
|
|
+@item -r @var{role}
|
|
+@itemx --role=@var{role}
|
|
+@opindex -r
|
|
+@opindex --role
|
|
+Set role @var{role} in the target security context.
|
|
+
|
|
+@item -t @var{type}
|
|
+@itemx --type=@var{type}
|
|
+@opindex -t
|
|
+@opindex --type
|
|
+Set type @var{type} in the target security context.
|
|
+
|
|
+@item -l @var{range}
|
|
+@itemx --range=@var{range}
|
|
+@opindex -l
|
|
+@opindex --range
|
|
+Set range @var{range} in the target security context.
|
|
+
|
|
+@end table
|
|
+
|
|
+@cindex exit status of @command{runcon}
|
|
+Exit status:
|
|
+
|
|
+@display
|
|
+126 if @var{command} is found but cannot be invoked
|
|
+127 if @command{runcon} itself fails or if @var{command} cannot be found
|
|
+the exit status of @var{command} otherwise
|
|
+@end display
|
|
+
|
|
+@node Modified command invocation
|
|
+@chapter Modified command invocation
|
|
+
|
|
+@cindex modified command invocation
|
|
+@cindex invocation of commands, modified
|
|
+@cindex commands for invoking other commands
|
|
+
|
|
+This section describes commands that run other commands in some context
|
|
+different than the current one: a modified environment, as a different
|
|
+user, etc.
|
|
+
|
|
+@menu
|
|
+* chroot invocation:: Modify the root directory.
|
|
+* env invocation:: Modify environment variables.
|
|
+* nice invocation:: Modify niceness.
|
|
+* nohup invocation:: Immunize to hangups.
|
|
+* stdbuf invocation:: Modify buffering of standard streams.
|
|
+* su invocation:: Modify user and group ID.
|
|
+* timeout invocation:: Run with time limit.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node chroot invocation
|
|
+@section @command{chroot}: Run a command with a different root directory
|
|
+
|
|
+@pindex chroot
|
|
+@cindex running a program in a specified root directory
|
|
+@cindex root directory, running a program in a specified
|
|
+
|
|
+@command{chroot} runs a command with a specified root directory.
|
|
+On many systems, only the super-user can do this.@footnote{However,
|
|
+some systems (e.g., FreeBSD) can be configured to allow certain regular
|
|
+users to use the @code{chroot} system call, and hence to run this program.
|
|
+Also, on Cygwin, anyone can run the @command{chroot} command, because the
|
|
+underlying function is non-privileged due to lack of support in MS-Windows.}
|
|
+Synopses:
|
|
+
|
|
+@example
|
|
+chroot @var{option} @var{newroot} [@var{command} [@var{args}]@dots{}]
|
|
+chroot @var{option}
|
|
+@end example
|
|
+
|
|
+Ordinarily, file names are looked up starting at the root of the
|
|
+directory structure, i.e., @file{/}. @command{chroot} changes the root to
|
|
+the directory @var{newroot} (which must exist) and then runs
|
|
+@var{command} with optional @var{args}. If @var{command} is not
|
|
+specified, the default is the value of the @env{SHELL} environment
|
|
+variable or @command{/bin/sh} if not set, invoked with the @option{-i} option.
|
|
+@var{command} must not be a special built-in utility
|
|
+(@pxref{Special built-in utilities}).
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+Options must precede operands.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@itemx --userspec=@var{user}[:@var{group}]
|
|
+@opindex --userspec
|
|
+By default, @var{command} is run with the same credentials
|
|
+as the invoking process.
|
|
+Use this option to run it as a different @var{user} and/or with a
|
|
+different primary @var{group}.
|
|
+
|
|
+@itemx --groups=@var{groups}
|
|
+@opindex --groups
|
|
+Use this option to specify the supplementary @var{groups} to be
|
|
+used by the new process.
|
|
+The items in the list (names or numeric IDs) must be separated by commas.
|
|
+
|
|
+@end table
|
|
+
|
|
+Here are a few tips to help avoid common problems in using chroot.
|
|
+To start with a simple example, make @var{command} refer to a statically
|
|
+linked binary. If you were to use a dynamically linked executable, then
|
|
+you'd have to arrange to have the shared libraries in the right place under
|
|
+your new root directory.
|
|
+
|
|
+For example, if you create a statically linked @command{ls} executable,
|
|
+and put it in @file{/tmp/empty}, you can run this command as root:
|
|
+
|
|
+@example
|
|
+$ chroot /tmp/empty /ls -Rl /
|
|
+@end example
|
|
+
|
|
+Then you'll see output like this:
|
|
+
|
|
+@example
|
|
+/:
|
|
+total 1023
|
|
+-rwxr-xr-x 1 0 0 1041745 Aug 16 11:17 ls
|
|
+@end example
|
|
+
|
|
+If you want to use a dynamically linked executable, say @command{bash},
|
|
+then first run @samp{ldd bash} to see what shared objects it needs.
|
|
+Then, in addition to copying the actual binary, also copy the listed
|
|
+files to the required positions under your intended new root directory.
|
|
+Finally, if the executable requires any other files (e.g., data, state,
|
|
+device files), copy them into place, too.
|
|
+
|
|
+@cindex exit status of @command{chroot}
|
|
+Exit status:
|
|
+
|
|
+@display
|
|
+1 if @command{chroot} itself fails
|
|
+126 if @var{command} is found but cannot be invoked
|
|
+127 if @var{command} cannot be found
|
|
+the exit status of @var{command} otherwise
|
|
+@end display
|
|
+
|
|
+
|
|
+@node env invocation
|
|
+@section @command{env}: Run a command in a modified environment
|
|
+
|
|
+@pindex env
|
|
+@cindex environment, running a program in a modified
|
|
+@cindex modified environment, running a program in a
|
|
+@cindex running a program in a modified environment
|
|
+
|
|
+@command{env} runs a command with a modified environment. Synopses:
|
|
+
|
|
+@example
|
|
+env [@var{option}]@dots{} [@var{name}=@var{value}]@dots{} @c
|
|
+[@var{command} [@var{args}]@dots{}]
|
|
+env
|
|
+@end example
|
|
+
|
|
+Operands of the form @samp{@var{variable}=@var{value}} set
|
|
+the environment variable @var{variable} to value @var{value}.
|
|
+@var{value} may be empty (@samp{@var{variable}=}). Setting a variable
|
|
+to an empty value is different from unsetting it.
|
|
+These operands are evaluated left-to-right, so if two operands
|
|
+mention the same variable the earlier is ignored.
|
|
+
|
|
+Environment variable names can be empty, and can contain any
|
|
+characters other than @samp{=} and @acronym{ASCII} @sc{nul}.
|
|
+However, it is wise to limit yourself to names that
|
|
+consist solely of underscores, digits, and @acronym{ASCII} letters,
|
|
+and that begin with a non-digit, as applications like the shell do not
|
|
+work well with other names.
|
|
+
|
|
+@vindex PATH
|
|
+The first operand that does not contain the character @samp{=}
|
|
+specifies the program to invoke; it is
|
|
+searched for according to the @env{PATH} environment variable. Any
|
|
+remaining arguments are passed as arguments to that program.
|
|
+The program should not be a special built-in utility
|
|
+(@pxref{Special built-in utilities}).
|
|
+
|
|
+@cindex environment, printing
|
|
+
|
|
+If no command name is specified following the environment
|
|
+specifications, the resulting environment is printed. This is like
|
|
+specifying the @command{printenv} program.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+Options must precede operands.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -u @var{name}
|
|
+@itemx --unset=@var{name}
|
|
+@opindex -u
|
|
+@opindex --unset
|
|
+Remove variable @var{name} from the environment, if it was in the
|
|
+environment.
|
|
+
|
|
+@item -
|
|
+@itemx -i
|
|
+@itemx --ignore-environment
|
|
+@opindex -
|
|
+@opindex -i
|
|
+@opindex --ignore-environment
|
|
+Start with an empty environment, ignoring the inherited environment.
|
|
+
|
|
+@end table
|
|
+
|
|
+@cindex exit status of @command{env}
|
|
+Exit status:
|
|
+
|
|
+@display
|
|
+0 if no @var{command} is specified and the environment is output
|
|
+1 if @command{env} itself fails
|
|
+126 if @var{command} is found but cannot be invoked
|
|
+127 if @var{command} cannot be found
|
|
+the exit status of @var{command} otherwise
|
|
+@end display
|
|
+
|
|
+
|
|
+@node nice invocation
|
|
+@section @command{nice}: Run a command with modified niceness
|
|
+
|
|
+@pindex nice
|
|
+@cindex niceness
|
|
+@cindex scheduling, affecting
|
|
+@cindex appropriate privileges
|
|
+
|
|
+@command{nice} prints or modifies a process's @dfn{niceness},
|
|
+a parameter that affects whether the process is scheduled favorably.
|
|
+Synopsis:
|
|
+
|
|
+@example
|
|
+nice [@var{option}]@dots{} [@var{command} [@var{arg}]@dots{}]
|
|
+@end example
|
|
+
|
|
+If no arguments are given, @command{nice} prints the current niceness.
|
|
+Otherwise, @command{nice} runs the given @var{command} with its
|
|
+niceness adjusted. By default, its niceness is incremented by 10.
|
|
+
|
|
+Niceness values range at least from @minus{}20 (process has high priority
|
|
+and gets more resources, thus slowing down other processes) through 19
|
|
+(process has lower priority and runs slowly itself, but has less impact
|
|
+on the speed of other running processes). Some systems
|
|
+may have a wider range of nicenesses; conversely, other systems may
|
|
+enforce more restrictive limits. An attempt to set the niceness
|
|
+outside the supported range is treated as an attempt to use the
|
|
+minimum or maximum supported value.
|
|
+
|
|
+A niceness should not be confused with a scheduling priority, which
|
|
+lets applications determine the order in which threads are scheduled
|
|
+to run. Unlike a priority, a niceness is merely advice to the
|
|
+scheduler, which the scheduler is free to ignore. Also, as a point of
|
|
+terminology, @acronym{POSIX} defines the behavior of @command{nice} in
|
|
+terms of a @dfn{nice value}, which is the nonnegative difference
|
|
+between a niceness and the minimum niceness. Though @command{nice}
|
|
+conforms to @acronym{POSIX}, its documentation and diagnostics use the
|
|
+term ``niceness'' for compatibility with historical practice.
|
|
+
|
|
+@var{command} must not be a special built-in utility (@pxref{Special
|
|
+built-in utilities}).
|
|
+
|
|
+@mayConflictWithShellBuiltIn{nice}
|
|
+
|
|
+The program accepts the following option. Also see @ref{Common options}.
|
|
+Options must precede operands.
|
|
+
|
|
+@table @samp
|
|
+@item -n @var{adjustment}
|
|
+@itemx --adjustment=@var{adjustment}
|
|
+@opindex -n
|
|
+@opindex --adjustment
|
|
+Add @var{adjustment} instead of 10 to the command's niceness. If
|
|
+@var{adjustment} is negative and you lack appropriate privileges,
|
|
+@command{nice} issues a warning but otherwise acts as if you specified
|
|
+a zero adjustment.
|
|
+
|
|
+For compatibility @command{nice} also supports an obsolete
|
|
+option syntax @option{-@var{adjustment}}. New scripts should use
|
|
+@option{-n @var{adjustment}} instead.
|
|
+
|
|
+@end table
|
|
+
|
|
+@cindex exit status of @command{nice}
|
|
+Exit status:
|
|
+
|
|
+@display
|
|
+0 if no @var{command} is specified and the niceness is output
|
|
+1 if @command{nice} itself fails
|
|
+126 if @var{command} is found but cannot be invoked
|
|
+127 if @var{command} cannot be found
|
|
+the exit status of @var{command} otherwise
|
|
+@end display
|
|
+
|
|
+It is sometimes useful to run a non-interactive program with reduced niceness.
|
|
+
|
|
+@example
|
|
+$ nice factor 4611686018427387903
|
|
+@end example
|
|
+
|
|
+Since @command{nice} prints the current niceness,
|
|
+you can invoke it through itself to demonstrate how it works.
|
|
+
|
|
+The default behavior is to increase the niceness by @samp{10}:
|
|
+
|
|
+@example
|
|
+$ nice
|
|
+0
|
|
+$ nice nice
|
|
+10
|
|
+$ nice -n 10 nice
|
|
+10
|
|
+@end example
|
|
+
|
|
+The @var{adjustment} is relative to the current niceness. In the
|
|
+next example, the first @command{nice} invocation runs the second one
|
|
+with niceness 10, and it in turn runs the final one with a niceness
|
|
+that is 3 more:
|
|
+
|
|
+@example
|
|
+$ nice nice -n 3 nice
|
|
+13
|
|
+@end example
|
|
+
|
|
+Specifying a niceness larger than the supported range
|
|
+is the same as specifying the maximum supported value:
|
|
+
|
|
+@example
|
|
+$ nice -n 10000000000 nice
|
|
+19
|
|
+@end example
|
|
+
|
|
+Only a privileged user may run a process with lower niceness:
|
|
+
|
|
+@example
|
|
+$ nice -n -1 nice
|
|
+nice: cannot set niceness: Permission denied
|
|
+0
|
|
+$ sudo nice -n -1 nice
|
|
+-1
|
|
+@end example
|
|
+
|
|
+
|
|
+@node nohup invocation
|
|
+@section @command{nohup}: Run a command immune to hangups
|
|
+
|
|
+@pindex nohup
|
|
+@cindex hangups, immunity to
|
|
+@cindex immunity to hangups
|
|
+@cindex logging out and continuing to run
|
|
+
|
|
+@flindex nohup.out
|
|
+@command{nohup} runs the given @var{command} with hangup signals ignored,
|
|
+so that the command can continue running in the background after you log
|
|
+out. Synopsis:
|
|
+
|
|
+@example
|
|
+nohup @var{command} [@var{arg}]@dots{}
|
|
+@end example
|
|
+
|
|
+If standard input is a terminal, it is redirected from
|
|
+@file{/dev/null} so that terminal sessions do not mistakenly consider
|
|
+the terminal to be used by the command. This is a @acronym{GNU}
|
|
+extension; programs intended to be portable to non-@acronym{GNU} hosts
|
|
+should use @samp{nohup @var{command} [@var{arg}]@dots{} </dev/null}
|
|
+instead.
|
|
+
|
|
+@flindex nohup.out
|
|
+If standard output is a terminal, the command's standard output is appended
|
|
+to the file @file{nohup.out}; if that cannot be written to, it is appended
|
|
+to the file @file{$HOME/nohup.out}; and if that cannot be written to, the
|
|
+command is not run.
|
|
+Any @file{nohup.out} or @file{$HOME/nohup.out} file created by
|
|
+@command{nohup} is made readable and writable only to the user,
|
|
+regardless of the current umask settings.
|
|
+
|
|
+If standard error is a terminal, it is normally redirected to the same file
|
|
+descriptor as the (possibly-redirected) standard output.
|
|
+However, if standard output is closed, standard error terminal output
|
|
+is instead appended to the file @file{nohup.out} or
|
|
+@file{$HOME/nohup.out} as above.
|
|
+
|
|
+To capture the command's output to a file other than @file{nohup.out}
|
|
+you can redirect it. For example, to capture the output of
|
|
+@command{make}:
|
|
+
|
|
+@example
|
|
+nohup make > make.log
|
|
+@end example
|
|
+
|
|
+@command{nohup} does not automatically put the command it runs in the
|
|
+background; you must do that explicitly, by ending the command line
|
|
+with an @samp{&}. Also, @command{nohup} does not alter the
|
|
+niceness of @var{command}; use @command{nice} for that,
|
|
+e.g., @samp{nohup nice @var{command}}.
|
|
+
|
|
+@var{command} must not be a special built-in utility (@pxref{Special
|
|
+built-in utilities}).
|
|
+
|
|
+The only options are @option{--help} and @option{--version}. @xref{Common
|
|
+options}. Options must precede operands.
|
|
+
|
|
+@cindex exit status of @command{nohup}
|
|
+Exit status:
|
|
+
|
|
+@display
|
|
+126 if @var{command} is found but cannot be invoked
|
|
+127 if @command{nohup} itself fails or if @var{command} cannot be found
|
|
+the exit status of @var{command} otherwise
|
|
+@end display
|
|
+
|
|
+
|
|
+@node stdbuf invocation
|
|
+@section @command{stdbuf}: Run a command with modified I/O stream buffering
|
|
+
|
|
+@pindex stdbuf
|
|
+@cindex standard streams, buffering
|
|
+@cindex line buffered
|
|
+
|
|
+@command{stdbuf} allows one to modify the buffering operations of the
|
|
+three standard I/O streams associated with a program. Synopsis:
|
|
+
|
|
+@example
|
|
+stdbuf @var{option}@dots{} @var{command}
|
|
+@end example
|
|
+
|
|
+Any additional @var{arg}s are passed as additional arguments to the
|
|
+@var{command}.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item -i @var{mode}
|
|
+@itemx --input=@var{mode}
|
|
+@opindex -i
|
|
+@opindex --input
|
|
+Adjust the standard input stream buffering.
|
|
+
|
|
+@item -o @var{mode}
|
|
+@itemx --output=@var{mode}
|
|
+@opindex -o
|
|
+@opindex --output
|
|
+Adjust the standard output stream buffering.
|
|
+
|
|
+@item -e @var{mode}
|
|
+@itemx --error=@var{mode}
|
|
+@opindex -e
|
|
+@opindex --error
|
|
+Adjust the standard error stream buffering.
|
|
+
|
|
+@end table
|
|
+
|
|
+The @var{mode} can be specified as follows:
|
|
+
|
|
+@table @samp
|
|
+
|
|
+@item L
|
|
+Set the stream to line buffered mode.
|
|
+In this mode data is coalesced until a newline is output or
|
|
+input is read from any stream attached to a terminal device.
|
|
+This option is invalid with standard input.
|
|
+
|
|
+@item 0
|
|
+Disable buffering of the selected stream.
|
|
+In this mode data is output immediately and only the
|
|
+amount of data requested is read from input.
|
|
+
|
|
+@item @var{size}
|
|
+Specify the size of the buffer to use in fully buffered mode.
|
|
+@multiplierSuffixesNoBlocks{size}
|
|
+
|
|
+@end table
|
|
+
|
|
+NOTE: If @var{command} adjusts the buffering of its standard streams
|
|
+(@command{tee} does for e.g.) then that will override corresponding settings
|
|
+changed by @command{stdbuf}. Also some filters (like @command{dd} and
|
|
+@command{cat} etc.) don't use streams for I/O, and are thus unaffected
|
|
+by @command{stdbuf} settings.
|
|
+
|
|
+@cindex exit status of @command{stdbuf}
|
|
+Exit status:
|
|
+
|
|
+@display
|
|
+125 if @command{stdbuf} itself fails
|
|
+126 if @var{command} is found but cannot be invoked
|
|
+127 if @var{command} cannot be found
|
|
+the exit status of @var{command} otherwise
|
|
+@end display
|
|
+
|
|
+
|
|
+@node su invocation
|
|
+@section @command{su}: Run a command with substitute user and group ID
|
|
+
|
|
+@pindex su
|
|
+@cindex substitute user and group IDs
|
|
+@cindex user ID, switching
|
|
+@cindex super-user, becoming
|
|
+@cindex root, becoming
|
|
+
|
|
+@command{su} allows one user to temporarily become another user. It runs a
|
|
+command (often an interactive shell) with the real and effective user
|
|
+ID, group ID, and supplemental groups of a given @var{user}. Synopsis:
|
|
+
|
|
+@example
|
|
+su [@var{option}]@dots{} [@var{user} [@var{arg}]@dots{}]
|
|
+@end example
|
|
+
|
|
+@cindex passwd entry, and @command{su} shell
|
|
+@flindex /bin/sh
|
|
+@flindex /etc/passwd
|
|
+If no @var{user} is given, the default is @code{root}, the super-user.
|
|
+The shell to use is taken from @var{user}'s @code{passwd} entry, or
|
|
+@file{/bin/sh} if none is specified there. If @var{user} has a
|
|
+password, @command{su} prompts for the password unless run by a user with
|
|
+effective user ID of zero (the super-user).
|
|
+
|
|
+@vindex HOME
|
|
+@vindex SHELL
|
|
+@vindex USER
|
|
+@vindex LOGNAME
|
|
+@cindex login shell
|
|
+By default, @command{su} does not change the current directory.
|
|
+It sets the environment variables @env{HOME} and @env{SHELL}
|
|
+from the password entry for @var{user}, and if @var{user} is not
|
|
+the super-user, sets @env{USER} and @env{LOGNAME} to @var{user}.
|
|
+By default, the shell is not a login shell.
|
|
+
|
|
+Any additional @var{arg}s are passed as additional arguments to the
|
|
+shell.
|
|
+
|
|
+@cindex @option{-su}
|
|
+GNU @command{su} does not treat @file{/bin/sh} or any other shells specially
|
|
+(e.g., by setting @code{argv[0]} to @option{-su}, passing @option{-c} only
|
|
+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.
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+
|
|
+@table @samp
|
|
+@item -c @var{command}
|
|
+@itemx --command=@var{command}
|
|
+@opindex -c
|
|
+@opindex --command
|
|
+Pass @var{command}, a single command line to run, to the shell with
|
|
+a @option{-c} option instead of starting an interactive shell.
|
|
+
|
|
+@item -f
|
|
+@itemx --fast
|
|
+@opindex -f
|
|
+@opindex --fast
|
|
+@flindex .cshrc
|
|
+@cindex file name pattern expansion, disabled
|
|
+@cindex globbing, disabled
|
|
+Pass the @option{-f} option to the shell. This probably only makes sense
|
|
+if the shell run is @command{csh} or @command{tcsh}, for which the @option{-f}
|
|
+option prevents reading the startup file (@file{.cshrc}). With
|
|
+Bourne-like shells, the @option{-f} option disables file name pattern
|
|
+expansion (globbing), which is not likely to be useful.
|
|
+
|
|
+@item -
|
|
+@itemx -l
|
|
+@itemx --login
|
|
+@opindex -
|
|
+@opindex -l
|
|
+@opindex --login
|
|
+@c other variables already indexed above
|
|
+@vindex TERM
|
|
+@vindex PATH
|
|
+@cindex login shell, creating
|
|
+Make the shell a login shell. This means the following. Unset all
|
|
+environment variables except @env{TERM}, @env{HOME}, and @env{SHELL}
|
|
+(which are set as described above), and @env{USER} and @env{LOGNAME}
|
|
+(which are set, even for the super-user, as described above), and set
|
|
+@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).
|
|
+
|
|
+@item -m
|
|
+@itemx -p
|
|
+@itemx --preserve-environment
|
|
+@opindex -m
|
|
+@opindex -p
|
|
+@opindex --preserve-environment
|
|
+@cindex environment, preserving
|
|
+@flindex /etc/shells
|
|
+@cindex restricted shell
|
|
+Do not change the environment variables @env{HOME}, @env{USER},
|
|
+@env{LOGNAME}, or @env{SHELL}. Run the shell given in the environment
|
|
+variable @env{SHELL} instead of the shell from @var{user}'s passwd
|
|
+entry, unless the user running @command{su} is not the super-user and
|
|
+@var{user}'s shell is restricted. A @dfn{restricted shell} is one that
|
|
+is not listed in the file @file{/etc/shells}, or in a compiled-in list
|
|
+if that file does not exist. Parts of what this option does can be
|
|
+overridden by @option{--login} and @option{--shell}.
|
|
+
|
|
+@item -s @var{shell}
|
|
+@itemx --shell=@var{shell}
|
|
+@opindex -s
|
|
+@opindex --shell
|
|
+Run @var{shell} instead of the shell from @var{user}'s passwd entry,
|
|
+unless the user running @command{su} is not the super-user and @var{user}'s
|
|
+shell is restricted (see @option{-m} just above).
|
|
+
|
|
+@end table
|
|
+
|
|
+@cindex exit status of @command{su}
|
|
+Exit status:
|
|
+
|
|
+@display
|
|
+1 if @command{su} itself fails
|
|
+126 if subshell is found but cannot be invoked
|
|
+127 if subshell cannot be found
|
|
+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
|
|
+
|
|
+@pindex timeout
|
|
+@cindex time limit
|
|
+@cindex run commands with bounded time
|
|
+
|
|
+@command{timeout} runs the given @var{command} and kills it if it is
|
|
+still running after the specified time interval. Synopsis:
|
|
+
|
|
+@example
|
|
+timeout [@var{option}] @var{number}[smhd] @var{command} [@var{arg}]@dots{}
|
|
+@end example
|
|
+
|
|
+@cindex time units
|
|
+@var{number} is an integer followed by an optional unit; the default
|
|
+is seconds. The units are:
|
|
+
|
|
+@table @samp
|
|
+@item s
|
|
+seconds
|
|
+@item m
|
|
+minutes
|
|
+@item h
|
|
+hours
|
|
+@item d
|
|
+days
|
|
+@end table
|
|
+
|
|
+@var{command} must not be a special built-in utility (@pxref{Special
|
|
+built-in utilities}).
|
|
+
|
|
+The program accepts the following option. Also see @ref{Common options}.
|
|
+Options must precede operands.
|
|
+
|
|
+@table @samp
|
|
+@item -s @var{signal}
|
|
+@itemx --signal=@var{signal}
|
|
+@opindex -s
|
|
+@opindex --signal
|
|
+Send this @var{signal} to @var{command} on timeout, rather than the
|
|
+default @samp{TERM} signal. @var{signal} may be a name like @samp{HUP}
|
|
+or a number. Also see @xref{Signal specifications}.
|
|
+
|
|
+@end table
|
|
+
|
|
+@cindex exit status of @command{timeout}
|
|
+Exit status:
|
|
+
|
|
+@display
|
|
+124 if @var{command} times out
|
|
+125 if @command{timeout} itself fails
|
|
+126 if @var{command} is found but cannot be invoked
|
|
+127 if @var{command} cannot be found
|
|
+the exit status of @var{command} otherwise
|
|
+@end display
|
|
+
|
|
+
|
|
+@node Process control
|
|
+@chapter Process control
|
|
+
|
|
+@cindex processes, commands for controlling
|
|
+@cindex commands for controlling processes
|
|
+
|
|
+@menu
|
|
+* kill invocation:: Sending a signal to processes.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node kill invocation
|
|
+@section @command{kill}: Send a signal to processes
|
|
+
|
|
+@pindex kill
|
|
+@cindex send a signal to processes
|
|
+
|
|
+The @command{kill} command sends a signal to processes, causing them
|
|
+to terminate or otherwise act upon receiving the signal in some way.
|
|
+Alternatively, it lists information about signals. Synopses:
|
|
+
|
|
+@example
|
|
+kill [-s @var{signal} | --signal @var{signal} | -@var{signal}] @var{pid}@dots{}
|
|
+kill [-l | --list | -t | --table] [@var{signal}]@dots{}
|
|
+@end example
|
|
+
|
|
+@mayConflictWithShellBuiltIn{kill}
|
|
+
|
|
+The first form of the @command{kill} command sends a signal to all
|
|
+@var{pid} arguments. The default signal to send if none is specified
|
|
+is @samp{TERM}. The special signal number @samp{0} does not denote a
|
|
+valid signal, but can be used to test whether the @var{pid} arguments
|
|
+specify processes to which a signal could be sent.
|
|
+
|
|
+If @var{pid} is positive, the signal is sent to the process with the
|
|
+process ID @var{pid}. If @var{pid} is zero, the signal is sent to all
|
|
+processes in the process group of the current process. If @var{pid}
|
|
+is @minus{}1, the signal is sent to all processes for which the user has
|
|
+permission to send a signal. If @var{pid} is less than @minus{}1, the signal
|
|
+is sent to all processes in the process group that equals the absolute
|
|
+value of @var{pid}.
|
|
+
|
|
+If @var{pid} is not positive, a system-dependent set of system
|
|
+processes is excluded from the list of processes to which the signal
|
|
+is sent.
|
|
+
|
|
+If a negative @var{pid} argument is desired as the first one, it
|
|
+should be preceded by @option{--}. However, as a common extension to
|
|
+@acronym{POSIX}, @option{--} is not required with @samp{kill
|
|
+-@var{signal} -@var{pid}}. The following commands are equivalent:
|
|
+
|
|
+@example
|
|
+kill -15 -1
|
|
+kill -TERM -1
|
|
+kill -s TERM -- -1
|
|
+kill -- -1
|
|
+@end example
|
|
+
|
|
+The first form of the @command{kill} command succeeds if every @var{pid}
|
|
+argument specifies at least one process that the signal was sent to.
|
|
+
|
|
+The second form of the @command{kill} command lists signal information.
|
|
+Either the @option{-l} or @option{--list} option, or the @option{-t}
|
|
+or @option{--table} option must be specified. Without any
|
|
+@var{signal} argument, all supported signals are listed. The output
|
|
+of @option{-l} or @option{--list} is a list of the signal names, one
|
|
+per line; if @var{signal} is already a name, the signal number is
|
|
+printed instead. The output of @option{-t} or @option{--table} is a
|
|
+table of signal numbers, names, and descriptions. This form of the
|
|
+@command{kill} command succeeds if all @var{signal} arguments are valid
|
|
+and if there is no output error.
|
|
+
|
|
+The @command{kill} command also supports the @option{--help} and
|
|
+@option{--version} options. @xref{Common options}.
|
|
+
|
|
+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, except for the
|
|
+@option{-@var{signal}} option which must use upper case to avoid
|
|
+ambiguity with lower case option letters. For a list of supported
|
|
+signal names and numbers see @xref{Signal specifications}.
|
|
+
|
|
+@node Delaying
|
|
+@chapter Delaying
|
|
+
|
|
+@cindex delaying commands
|
|
+@cindex commands for delaying
|
|
+
|
|
+@c Perhaps @command{wait} or other commands should be described here also?
|
|
+
|
|
+@menu
|
|
+* sleep invocation:: Delay for a specified time.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node sleep invocation
|
|
+@section @command{sleep}: Delay for a specified time
|
|
+
|
|
+@pindex sleep
|
|
+@cindex delay for a specified time
|
|
+
|
|
+@command{sleep} pauses for an amount of time specified by the sum of
|
|
+the values of the command line arguments.
|
|
+Synopsis:
|
|
+
|
|
+@example
|
|
+sleep @var{number}[smhd]@dots{}
|
|
+@end example
|
|
+
|
|
+@cindex time units
|
|
+Each argument is a number followed by an optional unit; the default
|
|
+is seconds. The units are:
|
|
+
|
|
+@table @samp
|
|
+@item s
|
|
+seconds
|
|
+@item m
|
|
+minutes
|
|
+@item h
|
|
+hours
|
|
+@item d
|
|
+days
|
|
+@end table
|
|
+
|
|
+Historical implementations of @command{sleep} have required that
|
|
+@var{number} be an integer, and only accepted a single argument
|
|
+without a suffix. However, GNU @command{sleep} accepts
|
|
+arbitrary floating point numbers (using a period before any fractional
|
|
+digits).
|
|
+
|
|
+The only options are @option{--help} and @option{--version}. @xref{Common
|
|
+options}.
|
|
+
|
|
+@c sleep is a shell built-in at least with Solaris 11's /bin/sh
|
|
+@mayConflictWithShellBuiltIn{sleep}
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node Numeric operations
|
|
+@chapter Numeric operations
|
|
+
|
|
+@cindex numeric operations
|
|
+These programs do numerically-related operations.
|
|
+
|
|
+@menu
|
|
+* factor invocation:: Show factors of numbers.
|
|
+* seq invocation:: Print sequences of numbers.
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node factor invocation
|
|
+@section @command{factor}: Print prime factors
|
|
+
|
|
+@pindex factor
|
|
+@cindex prime factors
|
|
+
|
|
+@command{factor} prints prime factors. Synopses:
|
|
+
|
|
+@example
|
|
+factor [@var{number}]@dots{}
|
|
+factor @var{option}
|
|
+@end example
|
|
+
|
|
+If no @var{number} is specified on the command line, @command{factor} reads
|
|
+numbers from standard input, delimited by newlines, tabs, or spaces.
|
|
+
|
|
+The @command{factor} command supports only a small number of options:
|
|
+
|
|
+@table @samp
|
|
+@item --help
|
|
+Print a short help on standard output, then exit without further
|
|
+processing.
|
|
+
|
|
+@item --version
|
|
+Print the program version on standard output, then exit without further
|
|
+processing.
|
|
+@end table
|
|
+
|
|
+Factoring the product of the eighth and ninth Mersenne primes
|
|
+takes about 30 milliseconds of CPU time on a 2.2 GHz Athlon.
|
|
+
|
|
+@example
|
|
+M8=`echo 2^31-1|bc` ; M9=`echo 2^61-1|bc`
|
|
+/usr/bin/time -f '%U' factor $(echo "$M8 * $M9" | bc)
|
|
+4951760154835678088235319297: 2147483647 2305843009213693951
|
|
+0.03
|
|
+@end example
|
|
+
|
|
+Similarly, factoring the eighth Fermat number @math{2^{256}+1} takes
|
|
+about 20 seconds on the same machine.
|
|
+
|
|
+Factoring large prime numbers is, in general, hard. The Pollard Rho
|
|
+algorithm used by @command{factor} is particularly effective for
|
|
+numbers with relatively small factors. If you wish to factor large
|
|
+numbers which do not have small factors (for example, numbers which
|
|
+are the product of two large primes), other methods are far better.
|
|
+
|
|
+If @command{factor} is built without using GNU MP, only
|
|
+single-precision arithmetic is available, and so large numbers
|
|
+(typically @math{2^{64}} and above) will not be supported. The single-precision
|
|
+code uses an algorithm which is designed for factoring smaller
|
|
+numbers.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node seq invocation
|
|
+@section @command{seq}: Print numeric sequences
|
|
+
|
|
+@pindex seq
|
|
+@cindex numeric sequences
|
|
+@cindex sequence of numbers
|
|
+
|
|
+@command{seq} prints a sequence of numbers to standard output. Synopses:
|
|
+
|
|
+@example
|
|
+seq [@var{option}]@dots{} @var{last}
|
|
+seq [@var{option}]@dots{} @var{first} @var{last}
|
|
+seq [@var{option}]@dots{} @var{first} @var{increment} @var{last}
|
|
+@end example
|
|
+
|
|
+@command{seq} prints the numbers from @var{first} to @var{last} by
|
|
+@var{increment}. By default, each number is printed on a separate line.
|
|
+When @var{increment} is not specified, it defaults to @samp{1},
|
|
+even when @var{first} is larger than @var{last}.
|
|
+@var{first} also defaults to @samp{1}. So @code{seq 1} prints
|
|
+@samp{1}, but @code{seq 0} and @code{seq 10 5} produce no output.
|
|
+Floating-point numbers
|
|
+may be specified (using a period before any fractional digits).
|
|
+
|
|
+The program accepts the following options. Also see @ref{Common options}.
|
|
+Options must precede operands.
|
|
+
|
|
+@table @samp
|
|
+@item -f @var{format}
|
|
+@itemx --format=@var{format}
|
|
+@opindex -f @var{format}
|
|
+@opindex --format=@var{format}
|
|
+@cindex formatting of numbers in @command{seq}
|
|
+Print all numbers using @var{format}.
|
|
+@var{format} must contain exactly one of the @samp{printf}-style
|
|
+floating point conversion specifications @samp{%a}, @samp{%e},
|
|
+@samp{%f}, @samp{%g}, @samp{%A}, @samp{%E}, @samp{%F}, @samp{%G}.
|
|
+The @samp{%} may be followed by zero or more flags taken from the set
|
|
+@samp{-+#0 '}, then an optional width containing one or more digits,
|
|
+then an optional precision consisting of a @samp{.} followed by zero
|
|
+or more digits. @var{format} may also contain any number of @samp{%%}
|
|
+conversion specifications. All conversion specifications have the
|
|
+same meaning as with @samp{printf}.
|
|
+
|
|
+The default format is derived from @var{first}, @var{step}, and
|
|
+@var{last}. If these all use a fixed point decimal representation,
|
|
+the default format is @samp{%.@var{p}f}, where @var{p} is the minimum
|
|
+precision that can represent the output numbers exactly. Otherwise,
|
|
+the default format is @samp{%g}.
|
|
+
|
|
+@item -s @var{string}
|
|
+@itemx --separator=@var{string}
|
|
+@cindex separator for numbers in @command{seq}
|
|
+Separate numbers with @var{string}; default is a newline.
|
|
+The output always terminates with a newline.
|
|
+
|
|
+@item -w
|
|
+@itemx --equal-width
|
|
+Print all numbers with the same width, by padding with leading zeros.
|
|
+@var{first}, @var{step}, and @var{last} should all use a fixed point
|
|
+decimal representation.
|
|
+(To have other kinds of padding, use @option{--format}).
|
|
+
|
|
+@end table
|
|
+
|
|
+You can get finer-grained control over output with @option{-f}:
|
|
+
|
|
+@example
|
|
+$ seq -f '(%9.2E)' -9e5 1.1e6 1.3e6
|
|
+(-9.00E+05)
|
|
+( 2.00E+05)
|
|
+( 1.30E+06)
|
|
+@end example
|
|
+
|
|
+If you want hexadecimal integer output, you can use @command{printf}
|
|
+to perform the conversion:
|
|
+
|
|
+@example
|
|
+$ printf '%x\n' `seq 1048575 1024 1050623`
|
|
+fffff
|
|
+1003ff
|
|
+1007ff
|
|
+@end example
|
|
+
|
|
+For very long lists of numbers, use xargs to avoid
|
|
+system limitations on the length of an argument list:
|
|
+
|
|
+@example
|
|
+$ seq 1000000 | xargs printf '%x\n' | tail -n 3
|
|
+f423e
|
|
+f423f
|
|
+f4240
|
|
+@end example
|
|
+
|
|
+To generate octal output, use the printf @code{%o} format instead
|
|
+of @code{%x}.
|
|
+
|
|
+On most systems, seq can produce whole-number output for values up to
|
|
+at least @math{2^{53}}. Larger integers are approximated. The details
|
|
+differ depending on your floating-point implementation, but a common
|
|
+case is that @command{seq} works with integers through @math{2^{64}},
|
|
+and larger integers may not be numerically correct:
|
|
+
|
|
+@example
|
|
+$ seq 18446744073709551616 1 18446744073709551618
|
|
+18446744073709551616
|
|
+18446744073709551616
|
|
+18446744073709551618
|
|
+@end example
|
|
+
|
|
+Be careful when using @command{seq} with outlandish values: otherwise
|
|
+you may see surprising results, as @command{seq} uses floating point
|
|
+internally. For example, on the x86 platform, where the internal
|
|
+representation uses a 64-bit fraction, the command:
|
|
+
|
|
+@example
|
|
+seq 1 0.0000000000000000001 1.0000000000000000009
|
|
+@end example
|
|
+
|
|
+outputs 1.0000000000000000007 twice and skips 1.0000000000000000008.
|
|
+
|
|
+@exitstatus
|
|
+
|
|
+
|
|
+@node File permissions
|
|
+@chapter File permissions
|
|
+@include perm.texi
|
|
+
|
|
+@include getdate.texi
|
|
+
|
|
+@c What's GNU?
|
|
+@c Arnold Robbins
|
|
+@node Opening the software toolbox
|
|
+@chapter Opening the Software Toolbox
|
|
+
|
|
+An earlier version of this chapter appeared in
|
|
+@uref{http://www.linuxjournal.com/article.php?sid=2762, the
|
|
+@cite{What's GNU?} column of @cite{Linux Journal}, 2 (June, 1994)}.
|
|
+It was written by Arnold Robbins.
|
|
+
|
|
+@menu
|
|
+* 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
|
|
+@end menu
|
|
+
|
|
+
|
|
+@node Toolbox introduction
|
|
+@unnumberedsec Toolbox Introduction
|
|
+
|
|
+This month's column is only peripherally related to the GNU Project, in
|
|
+that it describes a number of the GNU tools on your GNU/Linux system and how they
|
|
+might be used. What it's really about is the ``Software Tools'' philosophy
|
|
+of program development and usage.
|
|
+
|
|
+The software tools philosophy was an important and integral concept
|
|
+in the initial design and development of Unix (of which Linux and GNU are
|
|
+essentially clones). Unfortunately, in the modern day press of
|
|
+Internetworking and flashy GUIs, it seems to have fallen by the
|
|
+wayside. This is a shame, since it provides a powerful mental model
|
|
+for solving many kinds of problems.
|
|
+
|
|
+Many people carry a Swiss Army knife around in their pants pockets (or
|
|
+purse). A Swiss Army knife is a handy tool to have: it has several knife
|
|
+blades, a screwdriver, tweezers, toothpick, nail file, corkscrew, and perhaps
|
|
+a number of other things on it. For the everyday, small miscellaneous jobs
|
|
+where you need a simple, general purpose tool, it's just the thing.
|
|
+
|
|
+On the other hand, an experienced carpenter doesn't build a house using
|
|
+a Swiss Army knife. Instead, he has a toolbox chock full of specialized
|
|
+tools---a saw, a hammer, a screwdriver, a plane, and so on. And he knows
|
|
+exactly when and where to use each tool; you won't catch him hammering nails
|
|
+with the handle of his screwdriver.
|
|
+
|
|
+The Unix developers at Bell Labs were all professional programmers and trained
|
|
+computer scientists. They had found that while a one-size-fits-all program
|
|
+might appeal to a user because there's only one program to use, in practice
|
|
+such programs are
|
|
+
|
|
+@enumerate a
|
|
+@item
|
|
+difficult to write,
|
|
+
|
|
+@item
|
|
+difficult to maintain and
|
|
+debug, and
|
|
+
|
|
+@item
|
|
+difficult to extend to meet new situations.
|
|
+@end enumerate
|
|
+
|
|
+Instead, they felt that programs should be specialized tools. In short, each
|
|
+program ``should do one thing well.'' No more and no less. Such programs are
|
|
+simpler to design, write, and get right---they only do one thing.
|
|
+
|
|
+Furthermore, they found that with the right machinery for hooking programs
|
|
+together, that the whole was greater than the sum of the parts. By combining
|
|
+several special purpose programs, you could accomplish a specific task
|
|
+that none of the programs was designed for, and accomplish it much more
|
|
+quickly and easily than if you had to write a special purpose program.
|
|
+We will see some (classic) examples of this further on in the column.
|
|
+(An important additional point was that, if necessary, take a detour
|
|
+and build any software tools you may need first, if you don't already
|
|
+have something appropriate in the toolbox.)
|
|
+
|
|
+@node I/O redirection
|
|
+@unnumberedsec I/O Redirection
|
|
+
|
|
+Hopefully, you are familiar with the basics of I/O redirection in the
|
|
+shell, in particular the concepts of ``standard input,'' ``standard output,''
|
|
+and ``standard error''. Briefly, ``standard input'' is a data source, where
|
|
+data comes from. A program should not need to either know or care if the
|
|
+data source is a disk file, a keyboard, a magnetic tape, or even a punched
|
|
+card reader. Similarly, ``standard output'' is a data sink, where data goes
|
|
+to. The program should neither know nor care where this might be.
|
|
+Programs that only read their standard input, do something to the data,
|
|
+and then send it on, are called @dfn{filters}, by analogy to filters in a
|
|
+water pipeline.
|
|
+
|
|
+With the Unix shell, it's very easy to set up data pipelines:
|
|
+
|
|
+@smallexample
|
|
+program_to_create_data | filter1 | ... | filterN > final.pretty.data
|
|
+@end smallexample
|
|
+
|
|
+We start out by creating the raw data; each filter applies some successive
|
|
+transformation to the data, until by the time it comes out of the pipeline,
|
|
+it is in the desired form.
|
|
+
|
|
+This is fine and good for standard input and standard output. Where does the
|
|
+standard error come in to play? Well, think about @command{filter1} in
|
|
+the pipeline above. What happens if it encounters an error in the data it
|
|
+sees? If it writes an error message to standard output, it will just
|
|
+disappear down the pipeline into @command{filter2}'s input, and the
|
|
+user will probably never see it. So programs need a place where they can send
|
|
+error messages so that the user will notice them. This is standard error,
|
|
+and it is usually connected to your console or window, even if you have
|
|
+redirected standard output of your program away from your screen.
|
|
+
|
|
+For filter programs to work together, the format of the data has to be
|
|
+agreed upon. The most straightforward and easiest format to use is simply
|
|
+lines of text. Unix data files are generally just streams of bytes, with
|
|
+lines delimited by the @acronym{ASCII} @sc{lf} (Line Feed) character,
|
|
+conventionally called a ``newline'' in the Unix literature. (This is
|
|
+@code{'\n'} if you're a C programmer.) This is the format used by all
|
|
+the traditional filtering programs. (Many earlier operating systems
|
|
+had elaborate facilities and special purpose programs for managing
|
|
+binary data. Unix has always shied away from such things, under the
|
|
+philosophy that it's easiest to simply be able to view and edit your
|
|
+data with a text editor.)
|
|
+
|
|
+OK, enough introduction. Let's take a look at some of the tools, and then
|
|
+we'll see how to hook them together in interesting ways. In the following
|
|
+discussion, we will only present those command line options that interest
|
|
+us. As you should always do, double check your system documentation
|
|
+for the full story.
|
|
+
|
|
+@node The who command
|
|
+@unnumberedsec The @command{who} Command
|
|
+
|
|
+The first program is the @command{who} command. By itself, it generates a
|
|
+list of the users who are currently logged in. Although I'm writing
|
|
+this on a single-user system, we'll pretend that several people are
|
|
+logged in:
|
|
+
|
|
+@example
|
|
+$ who
|
|
+@print{} arnold console Jan 22 19:57
|
|
+@print{} miriam ttyp0 Jan 23 14:19(:0.0)
|
|
+@print{} bill ttyp1 Jan 21 09:32(:0.0)
|
|
+@print{} arnold ttyp2 Jan 23 20:48(:0.0)
|
|
+@end example
|
|
+
|
|
+Here, the @samp{$} is the usual shell prompt, at which I typed @samp{who}.
|
|
+There are three people logged in, and I am logged in twice. On traditional
|
|
+Unix systems, user names are never more than eight characters long. This
|
|
+little bit of trivia will be useful later. The output of @command{who} is nice,
|
|
+but the data is not all that exciting.
|
|
+
|
|
+@node The cut command
|
|
+@unnumberedsec The @command{cut} Command
|
|
+
|
|
+The next program we'll look at is the @command{cut} command. This program
|
|
+cuts out columns or fields of input data. For example, we can tell it
|
|
+to print just the login name and full name from the @file{/etc/passwd}
|
|
+file. The @file{/etc/passwd} file has seven fields, separated by
|
|
+colons:
|
|
+
|
|
+@example
|
|
+arnold:xyzzy:2076:10:Arnold D. Robbins:/home/arnold:/bin/bash
|
|
+@end example
|
|
+
|
|
+To get the first and fifth fields, we would use @command{cut} like this:
|
|
+
|
|
+@example
|
|
+$ cut -d: -f1,5 /etc/passwd
|
|
+@print{} root:Operator
|
|
+@dots{}
|
|
+@print{} arnold:Arnold D. Robbins
|
|
+@print{} miriam:Miriam A. Robbins
|
|
+@dots{}
|
|
+@end example
|
|
+
|
|
+With the @option{-c} option, @command{cut} will cut out specific characters
|
|
+(i.e., columns) in the input lines. This is useful for input data
|
|
+that has fixed width fields, and does not have a field separator. For
|
|
+example, list the Monday dates for the current month:
|
|
+
|
|
+@c Is using cal ok? Looked at gcal, but I don't like it.
|
|
+@example
|
|
+$ cal | cut -c 3-5
|
|
+@print{}Mo
|
|
+@print{}
|
|
+@print{} 6
|
|
+@print{} 13
|
|
+@print{} 20
|
|
+@print{} 27
|
|
+@end example
|
|
+
|
|
+@node The sort command
|
|
+@unnumberedsec The @command{sort} Command
|
|
+
|
|
+Next we'll look at the @command{sort} command. This is one of the most
|
|
+powerful commands on a Unix-style system; one that you will often find
|
|
+yourself using when setting up fancy data plumbing.
|
|
+
|
|
+The @command{sort}
|
|
+command reads and sorts each file named on the command line. It then
|
|
+merges the sorted data and writes it to standard output. It will read
|
|
+standard input if no files are given on the command line (thus
|
|
+making it into a filter). The sort is based on the character collating
|
|
+sequence or based on user-supplied ordering criteria.
|
|
+
|
|
+
|
|
+@node The uniq command
|
|
+@unnumberedsec The @command{uniq} Command
|
|
+
|
|
+Finally (at least for now), we'll look at the @command{uniq} program. When
|
|
+sorting data, you will often end up with duplicate lines, lines that
|
|
+are identical. Usually, all you need is one instance of each line.
|
|
+This is where @command{uniq} comes in. The @command{uniq} program reads its
|
|
+standard input. It prints only one
|
|
+copy of each repeated line. It does have several options. Later on,
|
|
+we'll use the @option{-c} option, which prints each unique line, preceded
|
|
+by a count of the number of times that line occurred in the input.
|
|
+
|
|
+
|
|
+@node Putting the tools together
|
|
+@unnumberedsec Putting the Tools Together
|
|
+
|
|
+Now, let's suppose this is a large ISP server system with dozens of users
|
|
+logged in. The management wants the system administrator to write a program that will
|
|
+generate a sorted list of logged in users. Furthermore, even if a user
|
|
+is logged in multiple times, his or her name should only show up in the
|
|
+output once.
|
|
+
|
|
+The administrator could sit down with the system documentation and write a C
|
|
+program that did this. It would take perhaps a couple of hundred lines
|
|
+of code and about two hours to write it, test it, and debug it.
|
|
+However, knowing the software toolbox, the administrator can instead start out
|
|
+by generating just a list of logged on users:
|
|
+
|
|
+@example
|
|
+$ who | cut -c1-8
|
|
+@print{} arnold
|
|
+@print{} miriam
|
|
+@print{} bill
|
|
+@print{} arnold
|
|
+@end example
|
|
+
|
|
+Next, sort the list:
|
|
+
|
|
+@example
|
|
+$ who | cut -c1-8 | sort
|
|
+@print{} arnold
|
|
+@print{} arnold
|
|
+@print{} bill
|
|
+@print{} miriam
|
|
+@end example
|
|
+
|
|
+Finally, run the sorted list through @command{uniq}, to weed out duplicates:
|
|
+
|
|
+@example
|
|
+$ who | cut -c1-8 | sort | uniq
|
|
+@print{} arnold
|
|
+@print{} bill
|
|
+@print{} miriam
|
|
+@end example
|
|
+
|
|
+The @command{sort} command actually has a @option{-u} option that does what
|
|
+@command{uniq} does. However, @command{uniq} has other uses for which one
|
|
+cannot substitute @samp{sort -u}.
|
|
+
|
|
+The administrator puts this pipeline into a shell script, and makes it available for
|
|
+all the users on the system (@samp{#} is the system administrator,
|
|
+or @code{root}, prompt):
|
|
+
|
|
+@example
|
|
+# cat > /usr/local/bin/listusers
|
|
+who | cut -c1-8 | sort | uniq
|
|
+^D
|
|
+# chmod +x /usr/local/bin/listusers
|
|
+@end example
|
|
+
|
|
+There are four major points to note here. First, with just four
|
|
+programs, on one command line, the administrator was able to save about two
|
|
+hours worth of work. Furthermore, the shell pipeline is just about as
|
|
+efficient as the C program would be, and it is much more efficient in
|
|
+terms of programmer time. People time is much more expensive than
|
|
+computer time, and in our modern ``there's never enough time to do
|
|
+everything'' society, saving two hours of programmer time is no mean
|
|
+feat.
|
|
+
|
|
+Second, it is also important to emphasize that with the
|
|
+@emph{combination} of the tools, it is possible to do a special
|
|
+purpose job never imagined by the authors of the individual programs.
|
|
+
|
|
+Third, it is also valuable to build up your pipeline in stages, as we did here.
|
|
+This allows you to view the data at each stage in the pipeline, which helps
|
|
+you acquire the confidence that you are indeed using these tools correctly.
|
|
+
|
|
+Finally, by bundling the pipeline in a shell script, other users can use
|
|
+your command, without having to remember the fancy plumbing you set up for
|
|
+them. In terms of how you run them, shell scripts and compiled programs are
|
|
+indistinguishable.
|
|
+
|
|
+After the previous warm-up exercise, we'll look at two additional, more
|
|
+complicated pipelines. For them, we need to introduce two more tools.
|
|
+
|
|
+The first is the @command{tr} command, which stands for ``transliterate.''
|
|
+The @command{tr} command works on a character-by-character basis, changing
|
|
+characters. Normally it is used for things like mapping upper case to
|
|
+lower case:
|
|
+
|
|
+@example
|
|
+$ echo ThIs ExAmPlE HaS MIXED case! | tr '[:upper:]' '[:lower:]'
|
|
+@print{} this example has mixed case!
|
|
+@end example
|
|
+
|
|
+There are several options of interest:
|
|
+
|
|
+@table @code
|
|
+@item -c
|
|
+work on the complement of the listed characters, i.e.,
|
|
+operations apply to characters not in the given set
|
|
+
|
|
+@item -d
|
|
+delete characters in the first set from the output
|
|
+
|
|
+@item -s
|
|
+squeeze repeated characters in the output into just one character.
|
|
+@end table
|
|
+
|
|
+We will be using all three options in a moment.
|
|
+
|
|
+The other command we'll look at is @command{comm}. The @command{comm}
|
|
+command takes two sorted input files as input data, and prints out the
|
|
+files' lines in three columns. The output columns are the data lines
|
|
+unique to the first file, the data lines unique to the second file, and
|
|
+the data lines that are common to both. The @option{-1}, @option{-2}, and
|
|
+@option{-3} command line options @emph{omit} the respective columns. (This is
|
|
+non-intuitive and takes a little getting used to.) For example:
|
|
+
|
|
+@example
|
|
+$ cat f1
|
|
+@print{} 11111
|
|
+@print{} 22222
|
|
+@print{} 33333
|
|
+@print{} 44444
|
|
+$ cat f2
|
|
+@print{} 00000
|
|
+@print{} 22222
|
|
+@print{} 33333
|
|
+@print{} 55555
|
|
+$ comm f1 f2
|
|
+@print{} 00000
|
|
+@print{} 11111
|
|
+@print{} 22222
|
|
+@print{} 33333
|
|
+@print{} 44444
|
|
+@print{} 55555
|
|
+@end example
|
|
+
|
|
+The file name @file{-} tells @command{comm} to read standard input
|
|
+instead of a regular file.
|
|
+
|
|
+Now we're ready to build a fancy pipeline. The first application is a word
|
|
+frequency counter. This helps an author determine if he or she is over-using
|
|
+certain words.
|
|
+
|
|
+The first step is to change the case of all the letters in our input file
|
|
+to one case. ``The'' and ``the'' are the same word when doing counting.
|
|
+
|
|
+@example
|
|
+$ tr '[:upper:]' '[:lower:]' < whats.gnu | ...
|
|
+@end example
|
|
+
|
|
+The next step is to get rid of punctuation. Quoted words and unquoted words
|
|
+should be treated identically; it's easiest to just get the punctuation out of
|
|
+the way.
|
|
+
|
|
+@smallexample
|
|
+$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | ...
|
|
+@end smallexample
|
|
+
|
|
+The second @command{tr} command operates on the complement of the listed
|
|
+characters, which are all the letters, the digits, the underscore, and
|
|
+the blank. The @samp{\n} represents the newline character; it has to
|
|
+be left alone. (The @acronym{ASCII} tab character should also be included for
|
|
+good measure in a production script.)
|
|
+
|
|
+At this point, we have data consisting of words separated by blank space.
|
|
+The words only contain alphanumeric characters (and the underscore). The
|
|
+next step is break the data apart so that we have one word per line. This
|
|
+makes the counting operation much easier, as we will see shortly.
|
|
+
|
|
+@smallexample
|
|
+$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
|
|
+> tr -s ' ' '\n' | ...
|
|
+@end smallexample
|
|
+
|
|
+This command turns blanks into newlines. The @option{-s} option squeezes
|
|
+multiple newline characters in the output into just one. This helps us
|
|
+avoid blank lines. (The @samp{>} is the shell's ``secondary prompt.''
|
|
+This is what the shell prints when it notices you haven't finished
|
|
+typing in all of a command.)
|
|
+
|
|
+We now have data consisting of one word per line, no punctuation, all one
|
|
+case. We're ready to count each word:
|
|
+
|
|
+@smallexample
|
|
+$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
|
|
+> tr -s ' ' '\n' | sort | uniq -c | ...
|
|
+@end smallexample
|
|
+
|
|
+At this point, the data might look something like this:
|
|
+
|
|
+@example
|
|
+ 60 a
|
|
+ 2 able
|
|
+ 6 about
|
|
+ 1 above
|
|
+ 2 accomplish
|
|
+ 1 acquire
|
|
+ 1 actually
|
|
+ 2 additional
|
|
+@end example
|
|
+
|
|
+The output is sorted by word, not by count! What we want is the most
|
|
+frequently used words first. Fortunately, this is easy to accomplish,
|
|
+with the help of two more @command{sort} options:
|
|
+
|
|
+@table @code
|
|
+@item -n
|
|
+do a numeric sort, not a textual one
|
|
+
|
|
+@item -r
|
|
+reverse the order of the sort
|
|
+@end table
|
|
+
|
|
+The final pipeline looks like this:
|
|
+
|
|
+@smallexample
|
|
+$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
|
|
+> tr -s ' ' '\n' | sort | uniq -c | sort -n -r
|
|
+@print{} 156 the
|
|
+@print{} 60 a
|
|
+@print{} 58 to
|
|
+@print{} 51 of
|
|
+@print{} 51 and
|
|
+@dots{}
|
|
+@end smallexample
|
|
+
|
|
+Whew! That's a lot to digest. Yet, the same principles apply. With six
|
|
+commands, on two lines (really one long one split for convenience), we've
|
|
+created a program that does something interesting and useful, in much
|
|
+less time than we could have written a C program to do the same thing.
|
|
+
|
|
+A minor modification to the above pipeline can give us a simple spelling
|
|
+checker! To determine if you've spelled a word correctly, all you have to
|
|
+do is look it up in a dictionary. If it is not there, then chances are
|
|
+that your spelling is incorrect. So, we need a dictionary.
|
|
+The conventional location for a dictionary is @file{/usr/dict/words}.
|
|
+On my GNU/Linux system,@footnote{Redhat Linux 6.1, for the November 2000
|
|
+revision of this article.}
|
|
+this is a sorted, 45,402 word dictionary.
|
|
+
|
|
+Now, how to compare our file with the dictionary? As before, we generate
|
|
+a sorted list of words, one per line:
|
|
+
|
|
+@smallexample
|
|
+$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
|
|
+> tr -s ' ' '\n' | sort -u | ...
|
|
+@end smallexample
|
|
+
|
|
+Now, all we need is a list of words that are @emph{not} in the
|
|
+dictionary. Here is where the @command{comm} command comes in.
|
|
+
|
|
+@smallexample
|
|
+$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
|
|
+> tr -s ' ' '\n' | sort -u |
|
|
+> comm -23 - /usr/dict/words
|
|
+@end smallexample
|
|
+
|
|
+The @option{-2} and @option{-3} options eliminate lines that are only in the
|
|
+dictionary (the second file), and lines that are in both files. Lines
|
|
+only in the first file (standard input, our stream of words), are
|
|
+words that are not in the dictionary. These are likely candidates for
|
|
+spelling errors. This pipeline was the first cut at a production
|
|
+spelling checker on Unix.
|
|
+
|
|
+There are some other tools that deserve brief mention.
|
|
+
|
|
+@table @command
|
|
+@item grep
|
|
+search files for text that matches a regular expression
|
|
+
|
|
+@item wc
|
|
+count lines, words, characters
|
|
+
|
|
+@item tee
|
|
+a T-fitting for data pipes, copies data to files and to standard output
|
|
+
|
|
+@item sed
|
|
+the stream editor, an advanced tool
|
|
+
|
|
+@item awk
|
|
+a data manipulation language, another advanced tool
|
|
+@end table
|
|
+
|
|
+The software tools philosophy also espoused the following bit of
|
|
+advice: ``Let someone else do the hard part.'' This means, take
|
|
+something that gives you most of what you need, and then massage it the
|
|
+rest of the way until it's in the form that you want.
|
|
+
|
|
+To summarize:
|
|
+
|
|
+@enumerate 1
|
|
+@item
|
|
+Each program should do one thing well. No more, no less.
|
|
+
|
|
+@item
|
|
+Combining programs with appropriate plumbing leads to results where
|
|
+the whole is greater than the sum of the parts. It also leads to novel
|
|
+uses of programs that the authors might never have imagined.
|
|
+
|
|
+@item
|
|
+Programs should never print extraneous header or trailer data, since these
|
|
+could get sent on down a pipeline. (A point we didn't mention earlier.)
|
|
+
|
|
+@item
|
|
+Let someone else do the hard part.
|
|
+
|
|
+@item
|
|
+Know your toolbox! Use each program appropriately. If you don't have an
|
|
+appropriate tool, build one.
|
|
+@end enumerate
|
|
+
|
|
+As of this writing, all the programs we've discussed are available via
|
|
+anonymous @command{ftp} from: @*
|
|
+@uref{ftp://gnudist.gnu.org/textutils/textutils-1.22.tar.gz}. (There may
|
|
+be more recent versions available now.)
|
|
+
|
|
+None of what I have presented in this column is new. The Software Tools
|
|
+philosophy was first introduced in the book @cite{Software Tools}, by
|
|
+Brian Kernighan and P.J. Plauger (Addison-Wesley, ISBN 0-201-03669-X).
|
|
+This book showed how to write and use software tools. It was written in
|
|
+1976, using a preprocessor for FORTRAN named @command{ratfor} (RATional
|
|
+FORtran). At the time, C was not as ubiquitous as it is now; FORTRAN
|
|
+was. The last chapter presented a @command{ratfor} to FORTRAN
|
|
+processor, written in @command{ratfor}. @command{ratfor} looks an awful
|
|
+lot like C; if you know C, you won't have any problem following the
|
|
+code.
|
|
+
|
|
+In 1981, the book was updated and made available as @cite{Software Tools
|
|
+in Pascal} (Addison-Wesley, ISBN 0-201-10342-7). Both books are
|
|
+still in print and are well worth
|
|
+reading if you're a programmer. They certainly made a major change in
|
|
+how I view programming.
|
|
+
|
|
+The programs in both books are available from
|
|
+@uref{http://cm.bell-labs.com/who/bwk, Brian Kernighan's home page}.
|
|
+For a number of years, there was an active
|
|
+Software Tools Users Group, whose members had ported the original
|
|
+@command{ratfor} programs to essentially every computer system with a
|
|
+FORTRAN compiler. The popularity of the group waned in the middle 1980s
|
|
+as Unix began to spread beyond universities.
|
|
+
|
|
+With the current proliferation of GNU code and other clones of Unix programs,
|
|
+these programs now receive little attention; modern C versions are
|
|
+much more efficient and do more than these programs do. Nevertheless, as
|
|
+exposition of good programming style, and evangelism for a still-valuable
|
|
+philosophy, these books are unparalleled, and I recommend them highly.
|
|
+
|
|
+Acknowledgment: I would like to express my gratitude to Brian Kernighan
|
|
+of Bell Labs, the original Software Toolsmith, for reviewing this column.
|
|
+
|
|
+@node GNU Free Documentation License
|
|
+@appendix GNU Free Documentation License
|
|
+
|
|
+@include fdl.texi
|
|
+
|
|
+@node Concept index
|
|
+@unnumbered Index
|
|
+
|
|
+@printindex cp
|
|
+
|
|
+@bye
|
|
+
|
|
+@c Local variables:
|
|
+@c texinfo-column-for-description: 32
|
|
+@c End:
|
|
diff -urNp coreutils-8.0-orig/src/Makefile.am coreutils-8.0/src/Makefile.am
|
|
--- coreutils-8.0-orig/src/Makefile.am 2009-09-21 14:29:33.000000000 +0200
|
|
+++ coreutils-8.0/src/Makefile.am 2009-10-07 10:04:27.000000000 +0200
|
|
@@ -154,7 +154,7 @@ tail_LDADD = $(nanosec_libs)
|
|
# If necessary, add -lm to resolve use of pow in lib/strtod.c.
|
|
uptime_LDADD = $(LDADD) $(POW_LIB) $(GETLOADAVG_LIBS)
|
|
|
|
-su_LDADD = $(LDADD) $(LIB_CRYPT)
|
|
+su_LDADD = $(LDADD) $(LIB_CRYPT) @LIB_PAM@
|
|
|
|
dir_LDADD += $(LIB_ACL)
|
|
ls_LDADD += $(LIB_ACL)
|
|
diff -urNp coreutils-8.0-orig/src/Makefile.am.orig coreutils-8.0/src/Makefile.am.orig
|
|
--- coreutils-8.0-orig/src/Makefile.am.orig 1970-01-01 01:00:00.000000000 +0100
|
|
+++ coreutils-8.0/src/Makefile.am.orig 2009-09-21 14:29:33.000000000 +0200
|
|
@@ -0,0 +1,480 @@
|
|
+## Process this file with automake to produce Makefile.in -*-Makefile-*-
|
|
+
|
|
+## Copyright (C) 1990, 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/>.
|
|
+
|
|
+# These are the names of programs that are not installed by default.
|
|
+# This list is *not* intended for programs like who, nice, chroot, etc.,
|
|
+# that are built only when certain requisite system features are detected.
|
|
+# Hence, if you want to install programs from this list anyway, say A and B,
|
|
+# use --enable-install-program=A,B
|
|
+no_install__progs = \
|
|
+ arch hostname su
|
|
+
|
|
+build_if_possible__progs = \
|
|
+ chroot df hostid nice pinky stdbuf libstdbuf.so stty su uname uptime users who
|
|
+
|
|
+AM_CFLAGS = $(WARN_CFLAGS) $(WERROR_CFLAGS)
|
|
+
|
|
+EXTRA_PROGRAMS = \
|
|
+ $(no_install__progs) \
|
|
+ $(build_if_possible__progs) \
|
|
+ [ chcon chgrp chown chmod cp dd dircolors du \
|
|
+ ginstall link ln dir vdir ls mkdir \
|
|
+ mkfifo mknod mktemp \
|
|
+ mv nohup readlink rm rmdir shred stat sync touch unlink \
|
|
+ cat cksum comm csplit cut expand fmt fold head join groups md5sum \
|
|
+ nl od paste pr ptx sha1sum sha224sum sha256sum sha384sum sha512sum \
|
|
+ shuf sort split sum tac tail tr tsort unexpand uniq wc \
|
|
+ basename date dirname echo env expr factor false \
|
|
+ id kill logname pathchk printenv printf pwd \
|
|
+ runcon seq sleep tee \
|
|
+ test timeout true truncate tty whoami yes \
|
|
+ base64
|
|
+
|
|
+bin_PROGRAMS = $(OPTIONAL_BIN_PROGS)
|
|
+
|
|
+noinst_PROGRAMS = setuidgid getlimits
|
|
+
|
|
+pkglib_PROGRAMS = $(OPTIONAL_PKGLIB_PROGS)
|
|
+
|
|
+noinst_HEADERS = \
|
|
+ chown-core.h \
|
|
+ copy.h \
|
|
+ cp-hash.h \
|
|
+ dircolors.h \
|
|
+ fs.h \
|
|
+ group-list.h \
|
|
+ ls.h \
|
|
+ operand2sig.h \
|
|
+ prog-fprintf.h \
|
|
+ remove.h \
|
|
+ system.h \
|
|
+ wheel-size.h \
|
|
+ wheel.h \
|
|
+ uname.h
|
|
+
|
|
+EXTRA_DIST = dcgen dircolors.hin tac-pipe.c \
|
|
+ wheel-gen.pl extract-magic c99-to-c89.diff
|
|
+BUILT_SOURCES =
|
|
+CLEANFILES = $(SCRIPTS) su
|
|
+
|
|
+# Also remove these sometimes-built programs.
|
|
+# For example, even when excluded, they're built via sc_check-AUTHORS.
|
|
+CLEANFILES += $(no_install__progs)
|
|
+
|
|
+AM_CPPFLAGS = -I$(top_srcdir)/lib
|
|
+
|
|
+noinst_LIBRARIES = libver.a
|
|
+nodist_libver_a_SOURCES = version.c version.h
|
|
+
|
|
+# Sometimes, the expansion of $(LIBINTL) includes -lc which may
|
|
+# include modules defining variables like `optind', so libcoreutils.a
|
|
+# must precede $(LIBINTL) in order to ensure we use GNU getopt.
|
|
+# But libcoreutils.a must also follow $(LIBINTL), since libintl uses
|
|
+# replacement functions defined in libcoreutils.a.
|
|
+LDADD = libver.a ../lib/libcoreutils.a $(LIBINTL) ../lib/libcoreutils.a
|
|
+
|
|
+cat_LDADD = $(LDADD)
|
|
+df_LDADD = $(LDADD)
|
|
+du_LDADD = $(LDADD)
|
|
+getlimits_LDADD = $(LDADD)
|
|
+ptx_LDADD = $(LDADD)
|
|
+split_LDADD = $(LDADD)
|
|
+stdbuf_LDADD = $(LDADD)
|
|
+timeout_LDADD = $(LDADD)
|
|
+truncate_LDADD = $(LDADD)
|
|
+
|
|
+# for eaccess in lib/euidaccess.c.
|
|
+chcon_LDADD = $(LDADD) $(LIB_SELINUX)
|
|
+cp_LDADD = $(LDADD) $(LIB_EACCESS) $(LIB_SELINUX)
|
|
+ginstall_LDADD = $(LDADD) $(LIB_EACCESS) $(LIB_SELINUX)
|
|
+mkdir_LDADD = $(LDADD) $(LIB_SELINUX)
|
|
+mkfifo_LDADD = $(LDADD) $(LIB_SELINUX)
|
|
+mknod_LDADD = $(LDADD) $(LIB_SELINUX)
|
|
+mv_LDADD = $(LDADD) $(LIB_EACCESS) $(LIB_SELINUX)
|
|
+runcon_LDADD = $(LDADD) $(LIB_SELINUX)
|
|
+pathchk_LDADD = $(LDADD) $(LIB_EACCESS)
|
|
+rm_LDADD = $(LDADD) $(LIB_EACCESS)
|
|
+test_LDADD = $(LDADD) $(LIB_EACCESS)
|
|
+# This is for the '[' program. Automake transliterates '[' to '_'.
|
|
+__LDADD = $(LDADD) $(LIB_EACCESS)
|
|
+
|
|
+# for clock_gettime and fdatasync
|
|
+dd_LDADD = $(LDADD) $(LIB_GETHRXTIME) $(LIB_FDATASYNC)
|
|
+dir_LDADD = $(LDADD) $(LIB_CLOCK_GETTIME) $(LIB_SELINUX) $(LIB_CAP)
|
|
+id_LDADD = $(LDADD) $(LIB_SELINUX)
|
|
+ls_LDADD = $(LDADD) $(LIB_CLOCK_GETTIME) $(LIB_SELINUX) $(LIB_CAP)
|
|
+mktemp_LDADD = $(LDADD) $(LIB_GETHRXTIME)
|
|
+pr_LDADD = $(LDADD) $(LIB_CLOCK_GETTIME)
|
|
+shred_LDADD = $(LDADD) $(LIB_GETHRXTIME) $(LIB_FDATASYNC)
|
|
+shuf_LDADD = $(LDADD) $(LIB_GETHRXTIME)
|
|
+tac_LDADD = $(LDADD) $(LIB_CLOCK_GETTIME)
|
|
+vdir_LDADD = $(LDADD) $(LIB_CLOCK_GETTIME) $(LIB_SELINUX) $(LIB_CAP)
|
|
+
|
|
+## If necessary, add -lm to resolve use of pow in lib/strtod.c.
|
|
+sort_LDADD = $(LDADD) $(POW_LIB) $(LIB_GETHRXTIME)
|
|
+
|
|
+# for get_date and gettime
|
|
+date_LDADD = $(LDADD) $(LIB_CLOCK_GETTIME)
|
|
+touch_LDADD = $(LDADD) $(LIB_CLOCK_GETTIME)
|
|
+
|
|
+# If necessary, add -lm to resolve use of pow in lib/strtod.c.
|
|
+# If necessary, add -liconv to resolve use of iconv in lib/unicodeio.c.
|
|
+printf_LDADD = $(LDADD) $(POW_LIB) $(LIBICONV)
|
|
+
|
|
+# If necessary, add -lm to resolve use of pow in lib/strtod.c.
|
|
+seq_LDADD = $(LDADD) $(POW_LIB)
|
|
+
|
|
+# If necessary, add libraries to resolve the `pow' reference in lib/strtod.c
|
|
+# and the `nanosleep' reference in lib/xnanosleep.c.
|
|
+nanosec_libs = $(LDADD) $(POW_LIB) $(LIB_NANOSLEEP)
|
|
+
|
|
+# for various GMP functions
|
|
+expr_LDADD = $(LDADD) $(LIB_GMP)
|
|
+
|
|
+# for various GMP functions
|
|
+factor_LDADD = $(LDADD) $(LIB_GMP)
|
|
+
|
|
+sleep_LDADD = $(nanosec_libs)
|
|
+tail_LDADD = $(nanosec_libs)
|
|
+
|
|
+# If necessary, add -lm to resolve use of pow in lib/strtod.c.
|
|
+uptime_LDADD = $(LDADD) $(POW_LIB) $(GETLOADAVG_LIBS)
|
|
+
|
|
+su_LDADD = $(LDADD) $(LIB_CRYPT)
|
|
+
|
|
+dir_LDADD += $(LIB_ACL)
|
|
+ls_LDADD += $(LIB_ACL)
|
|
+vdir_LDADD += $(LIB_ACL)
|
|
+cp_LDADD += $(LIB_ACL) $(LIB_XATTR)
|
|
+mv_LDADD += $(LIB_ACL) $(LIB_XATTR)
|
|
+ginstall_LDADD += $(LIB_ACL) $(LIB_XATTR)
|
|
+
|
|
+stat_LDADD = $(LDADD) $(LIB_SELINUX)
|
|
+
|
|
+# Append $(LIBICONV) to each program that uses proper_name_utf8.
|
|
+cat_LDADD += $(LIBICONV)
|
|
+cp_LDADD += $(LIBICONV)
|
|
+df_LDADD += $(LIBICONV)
|
|
+du_LDADD += $(LIBICONV)
|
|
+getlimits_LDADD += $(LIBICONV)
|
|
+ptx_LDADD += $(LIBICONV)
|
|
+split_LDADD += $(LIBICONV)
|
|
+stdbuf_LDADD += $(LIBICONV)
|
|
+timeout_LDADD += $(LIBICONV)
|
|
+truncate_LDADD += $(LIBICONV)
|
|
+
|
|
+# programs that use getaddrinfo (e.g., via canon_host)
|
|
+pinky_LDADD = $(LDADD) $(GETADDRINFO_LIB)
|
|
+who_LDADD = $(LDADD) $(GETADDRINFO_LIB)
|
|
+
|
|
+$(PROGRAMS): ../lib/libcoreutils.a
|
|
+
|
|
+# Get the release year from ../lib/version-etc.c.
|
|
+RELEASE_YEAR = \
|
|
+ `sed -n '/.*COPYRIGHT_YEAR = \([0-9][0-9][0-9][0-9]\) };/s//\1/p' \
|
|
+ $(top_srcdir)/lib/version-etc.c`
|
|
+
|
|
+all-local: su$(EXEEXT)
|
|
+
|
|
+installed_su = $(DESTDIR)$(bindir)/`echo su|sed '$(transform)'`
|
|
+
|
|
+setuid_root_mode = a=rx,u+s
|
|
+
|
|
+install_su = \
|
|
+ if test "$(INSTALL_SU)" = yes; then \
|
|
+ p=su; \
|
|
+ echo " $(INSTALL_PROGRAM) $$p $(installed_su)"; \
|
|
+ $(INSTALL_PROGRAM) $$p $(installed_su); \
|
|
+ echo " chown root $(installed_su)"; \
|
|
+ chown root $(installed_su); \
|
|
+ echo " chmod $(setuid_root_mode) $(installed_su)"; \
|
|
+ chmod $(setuid_root_mode) $(installed_su); \
|
|
+ else \
|
|
+ :; \
|
|
+ fi
|
|
+
|
|
+install-root: su$(EXEEXT)
|
|
+ @$(install_su)
|
|
+
|
|
+install-exec-hook: su$(EXEEXT)
|
|
+ @if test "$(INSTALL_SU)" = yes; then \
|
|
+ TMPFILE=$(DESTDIR)$(bindir)/.su-$$$$; \
|
|
+ rm -f $$TMPFILE; \
|
|
+ echo > $$TMPFILE; \
|
|
+## See if we can create a setuid root executable in $(bindir).
|
|
+## If not, then don't even try to install su.
|
|
+ can_create_suid_root_executable=no; \
|
|
+ chown root $$TMPFILE > /dev/null 2>&1 \
|
|
+ && chmod $(setuid_root_mode) $$TMPFILE > /dev/null 2>&1 \
|
|
+ && can_create_suid_root_executable=yes; \
|
|
+ rm -f $$TMPFILE; \
|
|
+ if test $$can_create_suid_root_executable = yes; then \
|
|
+ $(install_su); \
|
|
+ else \
|
|
+ echo "WARNING: insufficient access; not installing su"; \
|
|
+ echo "NOTE: to install su, run 'make install-root' as root"; \
|
|
+ rm -f $(installed_su); \
|
|
+ fi; \
|
|
+ else :; \
|
|
+ fi
|
|
+
|
|
+uninstall-local:
|
|
+# Remove su only if it's one we installed.
|
|
+ @if test "$(INSTALL_SU)" = yes; then \
|
|
+ if grep '$(PACKAGE_NAME)' $(installed_su) > /dev/null 2>&1; then \
|
|
+ echo " rm -f $(installed_su)"; \
|
|
+ rm -f $(installed_su); \
|
|
+ else :; \
|
|
+ fi; \
|
|
+ fi
|
|
+
|
|
+copy_sources = copy.c cp-hash.c
|
|
+
|
|
+# Use `ginstall' in the definition of PROGRAMS and in dependencies to avoid
|
|
+# confusion with the `install' target. The install rule transforms `ginstall'
|
|
+# to install before applying any user-specified name transformations.
|
|
+
|
|
+transform = s/ginstall/install/; $(program_transform_name)
|
|
+ginstall_SOURCES = install.c prog-fprintf.c $(copy_sources)
|
|
+
|
|
+# This is for the '[' program. Automake transliterates '[' to '_'.
|
|
+__SOURCES = lbracket.c
|
|
+
|
|
+cp_SOURCES = cp.c $(copy_sources)
|
|
+dir_SOURCES = ls.c ls-dir.c
|
|
+vdir_SOURCES = ls.c ls-vdir.c
|
|
+id_SOURCES = id.c group-list.c
|
|
+groups_SOURCES = groups.c group-list.c
|
|
+ln_SOURCES = ln.c
|
|
+ls_SOURCES = ls.c ls-ls.c
|
|
+chown_SOURCES = chown.c chown-core.c
|
|
+chgrp_SOURCES = chgrp.c chown-core.c
|
|
+kill_SOURCES = kill.c operand2sig.c
|
|
+timeout_SOURCES = timeout.c operand2sig.c
|
|
+
|
|
+mv_SOURCES = mv.c remove.c $(copy_sources)
|
|
+rm_SOURCES = rm.c remove.c
|
|
+
|
|
+mkdir_SOURCES = mkdir.c prog-fprintf.c
|
|
+rmdir_SOURCES = rmdir.c prog-fprintf.c
|
|
+
|
|
+uname_SOURCES = uname.c uname-uname.c
|
|
+arch_SOURCES = uname.c uname-arch.c
|
|
+
|
|
+md5sum_SOURCES = md5sum.c
|
|
+md5sum_CPPFLAGS = -DHASH_ALGO_MD5=1 $(AM_CPPFLAGS)
|
|
+sha1sum_SOURCES = md5sum.c
|
|
+sha1sum_CPPFLAGS = -DHASH_ALGO_SHA1=1 $(AM_CPPFLAGS)
|
|
+sha224sum_SOURCES = md5sum.c
|
|
+sha224sum_CPPFLAGS = -DHASH_ALGO_SHA224=1 $(AM_CPPFLAGS)
|
|
+sha256sum_SOURCES = md5sum.c
|
|
+sha256sum_CPPFLAGS = -DHASH_ALGO_SHA256=1 $(AM_CPPFLAGS)
|
|
+sha384sum_SOURCES = md5sum.c
|
|
+sha384sum_CPPFLAGS = -DHASH_ALGO_SHA384=1 $(AM_CPPFLAGS)
|
|
+sha512sum_SOURCES = md5sum.c
|
|
+sha512sum_CPPFLAGS = -DHASH_ALGO_SHA512=1 $(AM_CPPFLAGS)
|
|
+
|
|
+ginstall_CPPFLAGS = -DENABLE_MATCHPATHCON=1 $(AM_CPPFLAGS)
|
|
+
|
|
+# Ensure we don't link against libcoreutils.a as that lib is
|
|
+# not compiled with -fPIC which causes issues on 64 bit at least
|
|
+libstdbuf_so_LDADD =
|
|
+
|
|
+# Note libstdbuf is only compiled if GCC is available
|
|
+# (as per the check in configure.ac), so these flags should be available.
|
|
+# libtool is probably required to relax this dependency.
|
|
+libstdbuf_so_LDFLAGS = -shared
|
|
+libstdbuf_so_CFLAGS = -fPIC $(AM_CFLAGS)
|
|
+
|
|
+editpl = sed -e 's,@''PERL''@,$(PERL),g'
|
|
+
|
|
+BUILT_SOURCES += dircolors.h
|
|
+dircolors.h: dcgen dircolors.hin
|
|
+ $(AM_V_GEN)rm -f $@ $@-t
|
|
+ $(AM_V_at)$(PERL) -w -- $(srcdir)/dcgen $(srcdir)/dircolors.hin > $@-t
|
|
+ $(AM_V_at)chmod a-w $@-t
|
|
+ $(AM_V_at)mv $@-t $@
|
|
+
|
|
+wheel_size = 5
|
|
+
|
|
+BUILT_SOURCES += wheel-size.h
|
|
+wheel-size.h: Makefile.am
|
|
+ $(AM_V_GEN)rm -f $@ $@-t
|
|
+ $(AM_V_at)echo '#define WHEEL_SIZE $(wheel_size)' > $@-t
|
|
+ $(AM_V_at)chmod a-w $@-t
|
|
+ $(AM_V_at)mv $@-t $@
|
|
+
|
|
+BUILT_SOURCES += wheel.h
|
|
+wheel.h: wheel-gen.pl Makefile.am
|
|
+ $(AM_V_GEN)rm -f $@ $@-t
|
|
+ $(AM_V_at)$(srcdir)/wheel-gen.pl $(wheel_size) > $@-t
|
|
+ $(AM_V_at)chmod a-w $@-t
|
|
+ $(AM_V_at)mv $@-t $@
|
|
+
|
|
+# false exits nonzero even with --help or --version.
|
|
+# test doesn't support --help or --version.
|
|
+# Tell automake to exempt then from that installcheck test.
|
|
+AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false test
|
|
+
|
|
+BUILT_SOURCES += fs.h
|
|
+fs.h: stat.c extract-magic
|
|
+ $(AM_V_GEN)rm -f $@
|
|
+ $(AM_V_at)$(PERL) $(srcdir)/extract-magic $(srcdir)/stat.c > $@t
|
|
+ $(AM_V_at)chmod a-w $@t
|
|
+ $(AM_V_at)mv $@t $@
|
|
+
|
|
+BUILT_SOURCES += version.c
|
|
+version.c: Makefile
|
|
+ $(AM_V_GEN)rm -f $@
|
|
+ $(AM_V_at)printf '#include <config.h>\n' > $@t
|
|
+ $(AM_V_at)printf 'char const *Version = "$(PACKAGE_VERSION)";\n' >> $@t
|
|
+ $(AM_V_at)chmod a-w $@t
|
|
+ $(AM_V_at)mv $@t $@
|
|
+
|
|
+BUILT_SOURCES += version.h
|
|
+version.h: Makefile
|
|
+ $(AM_V_GEN)rm -f $@
|
|
+ $(AM_V_at)printf 'extern char const *Version;\n' > $@t
|
|
+ $(AM_V_at)chmod a-w $@t
|
|
+ $(AM_V_at)mv $@t $@
|
|
+
|
|
+DISTCLEANFILES = version.c version.h
|
|
+MAINTAINERCLEANFILES = $(BUILT_SOURCES)
|
|
+
|
|
+# Sort in traditional ASCII order, regardless of the current locale;
|
|
+# otherwise we may get into trouble with distinct strings that the
|
|
+# current locale considers to be equal.
|
|
+ASSORT = LC_ALL=C sort
|
|
+
|
|
+all_programs = \
|
|
+ $(bin_PROGRAMS) \
|
|
+ $(bin_SCRIPTS) \
|
|
+ $(EXTRA_PROGRAMS)
|
|
+
|
|
+built_programs.list:
|
|
+ @echo $(bin_PROGRAMS) $(bin_SCRIPTS) | tr ' ' '\n' \
|
|
+ | sed -e 's,$(EXEEXT)$$,,' | $(ASSORT) -u | tr '\n' ' '
|
|
+
|
|
+all_programs.list:
|
|
+ @echo $(all_programs) | tr ' ' '\n' | sed -e 's,$(EXEEXT)$$,,' \
|
|
+ | $(ASSORT) -u
|
|
+
|
|
+# This is required because we have broken inter-directory dependencies:
|
|
+# in order to generate all man pages, even those for which we don't
|
|
+# install a binary, require that all programs be built at distribution time.
|
|
+dist-hook: $(all_programs)
|
|
+
|
|
+pm = progs-makefile
|
|
+pr = progs-readme
|
|
+# Ensure that the list of programs in README matches the list
|
|
+# of programs we can build.
|
|
+check: check-README check-duplicate-no-install
|
|
+.PHONY: check-README
|
|
+check-README:
|
|
+ $(AM_V_GEN)rm -rf $(pr) $(pm)
|
|
+ $(AM_V_at)echo $(all_programs) \
|
|
+ | tr -s ' ' '\n' | sed -e 's,$(EXEEXT)$$,,;s/ginstall/install/' \
|
|
+ | sed /libstdbuf/d \
|
|
+ | $(ASSORT) -u > $(pm) && \
|
|
+ sed -n '/^The programs .* are:/,/^[a-zA-Z]/p' $(top_srcdir)/README \
|
|
+ | sed -n '/^ */s///p' | tr -s ' ' '\n' > $(pr)
|
|
+ $(AM_V_at)diff $(pm) $(pr) && rm -rf $(pr) $(pm)
|
|
+
|
|
+# Ensure that a by-default-not-installed program (listed in
|
|
+# $(no_install__progs) is not also listed in $(EXTRA_PROGRAMS), because
|
|
+# if that were to happen, it *would* be installed by default.
|
|
+.PHONY: check-duplicate-no-install
|
|
+check-duplicate-no-install: tr
|
|
+ $(AM_V_GEN)test -z "`echo '$(EXTRA_PROGRAMS)'| ./tr ' ' '\n' | uniq -d`"
|
|
+
|
|
+# Ensure that the list of programs and author names is accurate.
|
|
+# We need a UTF8 locale. If a lack of locale support or a missing
|
|
+# translation inhibits printing of UTF-8 names, just skip this test.
|
|
+au_dotdot = authors-dotdot
|
|
+au_actual = authors-actual
|
|
+.PHONY: sc_check-AUTHORS
|
|
+sc_check-AUTHORS: $(all_programs)
|
|
+ $(AM_V_GEN)locale=en_US.UTF-8; \
|
|
+ LC_ALL="$$locale" ./cat --version \
|
|
+ | grep ' Torbjorn ' > /dev/null \
|
|
+ && { echo "$@: skipping this check"; exit 0; }; \
|
|
+ rm -f $(au_actual) $(au_dotdot); \
|
|
+ for i in `ls $(all_programs) | sed -e 's,$(EXEEXT)$$,,' \
|
|
+ | sed /libstdbuf/d \
|
|
+ | $(ASSORT) -u`; do \
|
|
+ test "$$i" = '[' && continue; \
|
|
+ exe=$$i; \
|
|
+ if test "$$i" = install; then \
|
|
+ exe=ginstall; \
|
|
+ elif test "$$i" = test; then \
|
|
+ exe='['; \
|
|
+ fi; \
|
|
+ LC_ALL="$$locale" ./$$exe --version \
|
|
+ | perl -0 -pi -e 's/,\n/, /gm' \
|
|
+ | sed -n -e '/Written by /{ s//'"$$i"': /;' \
|
|
+ -e 's/,* and /, /; s/\.$$//; p; }'; \
|
|
+ done > $(au_actual) && \
|
|
+ sed -n '/^[^ ][^ ]*:/p' $(top_srcdir)/AUTHORS > $(au_dotdot) && \
|
|
+ diff $(au_actual) $(au_dotdot) && rm -f $(au_actual) $(au_dotdot)
|
|
+
|
|
+# The following rule is not designed to be portable,
|
|
+# and relies on tools that not everyone has.
|
|
+
|
|
+# Most functions in src/*.c should have static scope.
|
|
+# Any that don't must be marked with `extern', but `main'
|
|
+# and `usage' are exceptions. They're always extern, but
|
|
+# don't need to be marked. Also functions starting with __
|
|
+# are exempted due to possibly being added by the compiler
|
|
+# (when compiled as a shared library for example).
|
|
+#
|
|
+# The second nm|grep checks for file-scope variables with `extern' scope.
|
|
+.PHONY: sc_tight_scope
|
|
+sc_tight_scope: $(bin_PROGRAMS)
|
|
+ $(AM_V_GEN)t=exceptions-$$$$; \
|
|
+ trap "s=$$?; rm -f $$t; exit $$s" 0 1 2 13 15; \
|
|
+ src=`for f in $(SOURCES); do \
|
|
+ test -f $$f && d= || d=$(srcdir)/; echo $$d$$f; done`; \
|
|
+ hdr=`for f in $(noinst_HEADERS); do \
|
|
+ test -f $$f && d= || d=$(srcdir)/; echo $$d$$f; done`; \
|
|
+ ( printf 'main\nusage\n_.*\n'; \
|
|
+ grep -h -A1 '^extern .*[^;]$$' $$src \
|
|
+ | grep -vE '^(extern |--)' | sed 's/ .*//'; \
|
|
+ perl -ne '/^extern (?:enum )?\S+ (\S*) \(/ and print "$$1\n"' $$hdr; \
|
|
+ ) | $(ASSORT) -u | sed 's/^/^/;s/$$/$$/' > $$t; \
|
|
+ nm -e *.$(OBJEXT) \
|
|
+ | sed -n 's/.* T //p' \
|
|
+ | sed 's/^_//' \
|
|
+ | grep -Ev -f $$t && \
|
|
+ { echo 'the above functions should have static scope' 1>&2; \
|
|
+ exit 1; } || : ; \
|
|
+ ( printf '^program_name$$\n'; \
|
|
+ perl -ne '/^extern .*?\**(\w+);/ and print "^$$1\$$\n"' \
|
|
+ $$hdr *.h ) | $(ASSORT) -u > $$t; \
|
|
+ nm -e *.$(OBJEXT) \
|
|
+ | sed -n 's/.* [BD] //p' \
|
|
+ | sed 's/^_//' \
|
|
+ | grep -Ev -f $$t && \
|
|
+ { echo 'the above variables should have static scope' 1>&2; \
|
|
+ exit 1; } || :
|
|
+
|
|
+# Use the just-built ./ginstall, when not cross-compiling.
|
|
+if CROSS_COMPILING
|
|
+cu_install_program = @INSTALL_PROGRAM@
|
|
+else
|
|
+cu_install_program = ./ginstall
|
|
+endif
|
|
+INSTALL_PROGRAM = $(cu_install_program)
|
|
diff -urNp coreutils-8.0-orig/src/su.c coreutils-8.0/src/su.c
|
|
--- coreutils-8.0-orig/src/su.c 2009-10-07 10:03:29.000000000 +0200
|
|
+++ coreutils-8.0/src/su.c 2009-10-07 10:04:27.000000000 +0200
|
|
@@ -37,6 +37,16 @@
|
|
restricts who can su to UID 0 accounts. RMS considers that to
|
|
be fascist.
|
|
|
|
+#ifdef USE_PAM
|
|
+
|
|
+ Actually, with PAM, su has nothing to do with whether or not a
|
|
+ wheel group is enforced by su. RMS tries to restrict your access
|
|
+ to a su which implements the wheel group, but PAM considers that
|
|
+ to be fascist, and gives the user/sysadmin the opportunity to
|
|
+ enforce a wheel group by proper editing of /etc/pam.conf
|
|
+
|
|
+#endif
|
|
+
|
|
Compile-time options:
|
|
-DSYSLOG_SUCCESS Log successful su's (by default, to root) with syslog.
|
|
-DSYSLOG_FAILURE Log failed su's (by default, to root) with syslog.
|
|
@@ -53,6 +63,15 @@
|
|
#include <pwd.h>
|
|
#include <grp.h>
|
|
|
|
+#ifdef USE_PAM
|
|
+# include <signal.h>
|
|
+# include <sys/wait.h>
|
|
+# include <sys/fsuid.h>
|
|
+# include <unistd.h>
|
|
+# include <security/pam_appl.h>
|
|
+# include <security/pam_misc.h>
|
|
+#endif /* USE_PAM */
|
|
+
|
|
#include "system.h"
|
|
#include "getpass.h"
|
|
|
|
@@ -120,12 +139,19 @@
|
|
/* The user to become if none is specified. */
|
|
#define DEFAULT_USER "root"
|
|
|
|
+#ifndef USE_PAM
|
|
char *crypt (char const *key, char const *salt);
|
|
+#endif
|
|
|
|
extern char **environ;
|
|
|
|
-static void run_shell (char const *, char const *, char **, size_t)
|
|
+static void run_shell (char const *, char const *, char **, size_t,
|
|
+ const struct passwd *)
|
|
+#ifdef USE_PAM
|
|
+ ;
|
|
+#else
|
|
ATTRIBUTE_NORETURN;
|
|
+#endif
|
|
|
|
/* If true, pass the `-f' option to the subshell. */
|
|
static bool fast_startup;
|
|
@@ -211,7 +237,26 @@ log_su (struct passwd const *pw, bool su
|
|
}
|
|
#endif
|
|
|
|
+#ifdef USE_PAM
|
|
+static pam_handle_t *pamh = NULL;
|
|
+static int retval;
|
|
+static struct pam_conv conv = {
|
|
+ misc_conv,
|
|
+ NULL
|
|
+};
|
|
+
|
|
+#define PAM_BAIL_P if (retval) { \
|
|
+ pam_end(pamh, PAM_SUCCESS); \
|
|
+ return 0; \
|
|
+}
|
|
+#define PAM_BAIL_P_VOID if (retval) { \
|
|
+ pam_end(pamh, PAM_SUCCESS); \
|
|
+return; \
|
|
+}
|
|
+#endif
|
|
+
|
|
/* Ask the user for a password.
|
|
+ If PAM is in use, let PAM ask for the password if necessary.
|
|
Return true if the user gives the correct password for entry PW,
|
|
false if not. Return true without asking for a password if run by UID 0
|
|
or if PW has an empty password. */
|
|
@@ -219,6 +264,44 @@ log_su (struct passwd const *pw, bool su
|
|
static bool
|
|
correct_password (const struct passwd *pw)
|
|
{
|
|
+#ifdef USE_PAM
|
|
+ struct passwd *caller;
|
|
+ char *tty_name, *ttyn;
|
|
+ retval = pam_start(PROGRAM_NAME, pw->pw_name, &conv, &pamh);
|
|
+ PAM_BAIL_P;
|
|
+
|
|
+ if (getuid() != 0 && !isatty(0)) {
|
|
+ fprintf(stderr, "standard in must be a tty\n");
|
|
+ exit(1);
|
|
+ }
|
|
+
|
|
+ caller = getpwuid(getuid());
|
|
+ if(caller != NULL && caller->pw_name != NULL) {
|
|
+ retval = pam_set_item(pamh, PAM_RUSER, caller->pw_name);
|
|
+ PAM_BAIL_P;
|
|
+ }
|
|
+
|
|
+ ttyn = ttyname(0);
|
|
+ if (ttyn) {
|
|
+ if (strncmp(ttyn, "/dev/", 5) == 0)
|
|
+ tty_name = ttyn+5;
|
|
+ else
|
|
+ tty_name = ttyn;
|
|
+ retval = pam_set_item(pamh, PAM_TTY, tty_name);
|
|
+ PAM_BAIL_P;
|
|
+ }
|
|
+ retval = pam_authenticate(pamh, 0);
|
|
+ PAM_BAIL_P;
|
|
+ retval = pam_acct_mgmt(pamh, 0);
|
|
+ if (retval == PAM_NEW_AUTHTOK_REQD) {
|
|
+ /* password has expired. Offer option to change it. */
|
|
+ retval = pam_chauthtok(pamh, PAM_CHANGE_EXPIRED_AUTHTOK);
|
|
+ PAM_BAIL_P;
|
|
+ }
|
|
+ PAM_BAIL_P;
|
|
+ /* must be authenticated if this point was reached */
|
|
+ return 1;
|
|
+#else /* !USE_PAM */
|
|
char *unencrypted, *encrypted, *correct;
|
|
#if HAVE_GETSPNAM && HAVE_STRUCT_SPWD_SP_PWDP
|
|
/* Shadow passwd stuff for SVR3 and maybe other systems. */
|
|
@@ -243,6 +326,7 @@ correct_password (const struct passwd *p
|
|
encrypted = crypt (unencrypted, correct);
|
|
memset (unencrypted, 0, strlen (unencrypted));
|
|
return STREQ (encrypted, correct);
|
|
+#endif /* !USE_PAM */
|
|
}
|
|
|
|
/* Update `environ' for the new shell based on PW, with SHELL being
|
|
@@ -256,12 +340,18 @@ modify_environment (const struct passwd
|
|
/* Leave TERM unchanged. Set HOME, SHELL, USER, LOGNAME, PATH.
|
|
Unset all other environment variables. */
|
|
char const *term = getenv ("TERM");
|
|
+ char const *display = getenv ("DISPLAY");
|
|
+ char const *xauthority = getenv ("XAUTHORITY");
|
|
if (term)
|
|
term = xstrdup (term);
|
|
environ = xmalloc ((6 + !!term) * sizeof (char *));
|
|
environ[0] = NULL;
|
|
if (term)
|
|
xsetenv ("TERM", term);
|
|
+ if (display)
|
|
+ xsetenv ("DISPLAY", display);
|
|
+ if (xauthority)
|
|
+ xsetenv ("XAUTHORITY", xauthority);
|
|
xsetenv ("HOME", pw->pw_dir);
|
|
xsetenv ("SHELL", shell);
|
|
xsetenv ("USER", pw->pw_name);
|
|
@@ -294,8 +384,13 @@ change_identity (const struct passwd *pw
|
|
{
|
|
#ifdef HAVE_INITGROUPS
|
|
errno = 0;
|
|
- if (initgroups (pw->pw_name, pw->pw_gid) == -1)
|
|
+ if (initgroups (pw->pw_name, pw->pw_gid) == -1) {
|
|
+#ifdef USE_PAM
|
|
+ pam_close_session(pamh, 0);
|
|
+ pam_end(pamh, PAM_ABORT);
|
|
+#endif
|
|
error (EXIT_FAILURE, errno, _("cannot set groups"));
|
|
+ }
|
|
endgrent ();
|
|
#endif
|
|
if (setgid (pw->pw_gid))
|
|
@@ -304,6 +399,31 @@ change_identity (const struct passwd *pw
|
|
error (EXIT_FAILURE, errno, _("cannot set user id"));
|
|
}
|
|
|
|
+#ifdef USE_PAM
|
|
+static int caught=0;
|
|
+/* Signal handler for parent process later */
|
|
+static void su_catch_sig(int sig)
|
|
+{
|
|
+ ++caught;
|
|
+}
|
|
+
|
|
+int
|
|
+pam_copyenv (pam_handle_t *pamh)
|
|
+{
|
|
+ char **env;
|
|
+
|
|
+ env = pam_getenvlist(pamh);
|
|
+ if(env) {
|
|
+ while(*env) {
|
|
+ if (putenv (*env))
|
|
+ xalloc_die ();
|
|
+ env++;
|
|
+ }
|
|
+ }
|
|
+ return(0);
|
|
+}
|
|
+#endif
|
|
+
|
|
/* Run SHELL, or DEFAULT_SHELL if SHELL is empty.
|
|
If COMMAND is nonzero, pass it to the shell with the -c option.
|
|
Pass ADDITIONAL_ARGS to the shell as more arguments; there
|
|
@@ -311,17 +431,49 @@ change_identity (const struct passwd *pw
|
|
|
|
static void
|
|
run_shell (char const *shell, char const *command, char **additional_args,
|
|
- size_t n_additional_args)
|
|
+ size_t n_additional_args, const struct passwd *pw)
|
|
{
|
|
size_t n_args = 1 + fast_startup + 2 * !!command + n_additional_args + 1;
|
|
char const **args = xnmalloc (n_args, sizeof *args);
|
|
size_t argno = 1;
|
|
+#ifdef USE_PAM
|
|
+ int child;
|
|
+ sigset_t ourset;
|
|
+ int status;
|
|
+
|
|
+ retval = pam_open_session(pamh,0);
|
|
+ if (retval != PAM_SUCCESS) {
|
|
+ fprintf (stderr, "could not open session\n");
|
|
+ exit (1);
|
|
+ }
|
|
+
|
|
+/* do this at the last possible moment, because environment variables may
|
|
+ be passed even in the session phase
|
|
+*/
|
|
+ if(pam_copyenv(pamh) != PAM_SUCCESS)
|
|
+ fprintf (stderr, "error copying PAM environment\n");
|
|
+
|
|
+ /* Credentials should be set in the parent */
|
|
+ if (pam_setcred(pamh, PAM_ESTABLISH_CRED) != PAM_SUCCESS) {
|
|
+ pam_close_session(pamh, 0);
|
|
+ fprintf(stderr, "could not set PAM credentials\n");
|
|
+ exit(1);
|
|
+ }
|
|
+
|
|
+ child = fork();
|
|
+ if (child == 0) { /* child shell */
|
|
+ change_identity (pw);
|
|
+ pam_end(pamh, 0);
|
|
+#endif
|
|
|
|
if (simulate_login)
|
|
{
|
|
char *arg0;
|
|
char *shell_basename;
|
|
|
|
+ if(chdir(pw->pw_dir))
|
|
+ error(0, errno, _("warning: cannot change directory to %s"), pw->pw_dir);
|
|
+
|
|
shell_basename = last_component (shell);
|
|
arg0 = xmalloc (strlen (shell_basename) + 2);
|
|
arg0[0] = '-';
|
|
@@ -346,6 +498,66 @@ run_shell (char const *shell, char const
|
|
error (0, errno, "%s", shell);
|
|
exit (exit_status);
|
|
}
|
|
+#ifdef USE_PAM
|
|
+ } else if (child == -1) {
|
|
+ fprintf(stderr, "can not fork user shell: %s", strerror(errno));
|
|
+ pam_setcred(pamh, PAM_DELETE_CRED | PAM_SILENT);
|
|
+ pam_close_session(pamh, 0);
|
|
+ pam_end(pamh, PAM_ABORT);
|
|
+ exit(1);
|
|
+ }
|
|
+ /* parent only */
|
|
+ sigfillset(&ourset);
|
|
+ if (sigprocmask(SIG_BLOCK, &ourset, NULL)) {
|
|
+ fprintf(stderr, "%s: signal malfunction\n", PROGRAM_NAME);
|
|
+ caught = 1;
|
|
+ }
|
|
+ if (!caught) {
|
|
+ struct sigaction action;
|
|
+ action.sa_handler = su_catch_sig;
|
|
+ sigemptyset(&action.sa_mask);
|
|
+ action.sa_flags = 0;
|
|
+ sigemptyset(&ourset);
|
|
+ if (sigaddset(&ourset, SIGTERM)
|
|
+ || sigaddset(&ourset, SIGALRM)
|
|
+ || sigaction(SIGTERM, &action, NULL)
|
|
+ || sigprocmask(SIG_UNBLOCK, &ourset, NULL)) {
|
|
+ fprintf(stderr, "%s: signal masking malfunction\n", PROGRAM_NAME);
|
|
+ caught = 1;
|
|
+ }
|
|
+ }
|
|
+ if (!caught) {
|
|
+ do {
|
|
+ int pid;
|
|
+
|
|
+ pid = waitpid(-1, &status, WUNTRACED);
|
|
+
|
|
+ if (WIFSTOPPED(status)) {
|
|
+ kill(getpid(), SIGSTOP);
|
|
+ /* once we get here, we must have resumed */
|
|
+ kill(pid, SIGCONT);
|
|
+ }
|
|
+ } while (WIFSTOPPED(status));
|
|
+ }
|
|
+
|
|
+ if (caught) {
|
|
+ fprintf(stderr, "\nSession terminated, killing shell...");
|
|
+ kill (child, SIGTERM);
|
|
+ }
|
|
+ /* Not checking retval on this because we need to call close session */
|
|
+ pam_setcred(pamh, PAM_DELETE_CRED | PAM_SILENT);
|
|
+ retval = pam_close_session(pamh, 0);
|
|
+ PAM_BAIL_P_VOID;
|
|
+ retval = pam_end(pamh, PAM_SUCCESS);
|
|
+ PAM_BAIL_P_VOID;
|
|
+ if (caught) {
|
|
+ sleep(2);
|
|
+ kill(child, SIGKILL);
|
|
+ fprintf(stderr, " ...killed.\n");
|
|
+ exit(-1);
|
|
+ }
|
|
+ exit (WEXITSTATUS(status));
|
|
+#endif /* USE_PAM */
|
|
}
|
|
|
|
/* Return true if SHELL is a restricted shell (one not returned by
|
|
@@ -513,9 +725,9 @@ main (int argc, char **argv)
|
|
shell = xstrdup (shell ? shell : pw->pw_shell);
|
|
modify_environment (pw, shell);
|
|
|
|
+#ifndef USE_PAM
|
|
change_identity (pw);
|
|
- if (simulate_login && chdir (pw->pw_dir) != 0)
|
|
- error (0, errno, _("warning: cannot change directory to %s"), pw->pw_dir);
|
|
+#endif
|
|
|
|
- run_shell (shell, command, argv + optind, MAX (0, argc - optind));
|
|
+ run_shell (shell, command, argv + optind, MAX (0, argc - optind), pw);
|
|
}
|
|
diff -urNp coreutils-8.0-orig/src/su.c.orig coreutils-8.0/src/su.c.orig
|
|
--- coreutils-8.0-orig/src/su.c.orig 1970-01-01 01:00:00.000000000 +0100
|
|
+++ coreutils-8.0/src/su.c.orig 2009-10-07 10:03:29.000000000 +0200
|
|
@@ -0,0 +1,521 @@
|
|
+/* su for GNU. Run a shell with substitute user and group IDs.
|
|
+ Copyright (C) 1992-2006, 2008-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/>. */
|
|
+
|
|
+/* Run a shell with the real and effective UID and GID and groups
|
|
+ of USER, default `root'.
|
|
+
|
|
+ The shell run is taken from USER's password entry, /bin/sh if
|
|
+ none is specified there. If the account has a password, su
|
|
+ prompts for a password unless run by a user with real UID 0.
|
|
+
|
|
+ Does not change the current directory.
|
|
+ Sets `HOME' and `SHELL' from the password entry for USER, and if
|
|
+ USER is not root, sets `USER' and `LOGNAME' to USER.
|
|
+ The subshell is not a login shell.
|
|
+
|
|
+ If one or more ARGs are given, they are passed as additional
|
|
+ arguments to the subshell.
|
|
+
|
|
+ Does not handle /bin/sh or other shells specially
|
|
+ (setting argv[0] to "-su", passing -c only to certain shells, etc.).
|
|
+ I don't see the point in doing that, and it's ugly.
|
|
+
|
|
+ This program intentionally does not support a "wheel group" that
|
|
+ restricts who can su to UID 0 accounts. RMS considers that to
|
|
+ be fascist.
|
|
+
|
|
+ Compile-time options:
|
|
+ -DSYSLOG_SUCCESS Log successful su's (by default, to root) with syslog.
|
|
+ -DSYSLOG_FAILURE Log failed su's (by default, to root) with syslog.
|
|
+
|
|
+ -DSYSLOG_NON_ROOT Log all su's, not just those to root (UID 0).
|
|
+ Never logs attempted su's to nonexistent accounts.
|
|
+
|
|
+ Written by David MacKenzie <djm@gnu.ai.mit.edu>. */
|
|
+
|
|
+#include <config.h>
|
|
+#include <stdio.h>
|
|
+#include <getopt.h>
|
|
+#include <sys/types.h>
|
|
+#include <pwd.h>
|
|
+#include <grp.h>
|
|
+
|
|
+#include "system.h"
|
|
+#include "getpass.h"
|
|
+
|
|
+#if HAVE_SYSLOG_H && HAVE_SYSLOG
|
|
+# include <syslog.h>
|
|
+#else
|
|
+# undef SYSLOG_SUCCESS
|
|
+# undef SYSLOG_FAILURE
|
|
+# undef SYSLOG_NON_ROOT
|
|
+#endif
|
|
+
|
|
+#if HAVE_SYS_PARAM_H
|
|
+# include <sys/param.h>
|
|
+#endif
|
|
+
|
|
+#ifndef HAVE_ENDGRENT
|
|
+# define endgrent() ((void) 0)
|
|
+#endif
|
|
+
|
|
+#ifndef HAVE_ENDPWENT
|
|
+# define endpwent() ((void) 0)
|
|
+#endif
|
|
+
|
|
+#if HAVE_SHADOW_H
|
|
+# include <shadow.h>
|
|
+#endif
|
|
+
|
|
+#include "error.h"
|
|
+
|
|
+/* The official name of this program (e.g., no `g' prefix). */
|
|
+#define PROGRAM_NAME "su"
|
|
+
|
|
+#define AUTHORS proper_name ("David MacKenzie")
|
|
+
|
|
+#if HAVE_PATHS_H
|
|
+# include <paths.h>
|
|
+#endif
|
|
+
|
|
+/* The default PATH for simulated logins to non-superuser accounts. */
|
|
+#ifdef _PATH_DEFPATH
|
|
+# define DEFAULT_LOGIN_PATH _PATH_DEFPATH
|
|
+#else
|
|
+# define DEFAULT_LOGIN_PATH ":/usr/ucb:/bin:/usr/bin"
|
|
+#endif
|
|
+
|
|
+/* The default PATH for simulated logins to superuser accounts. */
|
|
+#ifdef _PATH_DEFPATH_ROOT
|
|
+# define DEFAULT_ROOT_LOGIN_PATH _PATH_DEFPATH_ROOT
|
|
+#else
|
|
+# define DEFAULT_ROOT_LOGIN_PATH "/usr/ucb:/bin:/usr/bin:/etc"
|
|
+#endif
|
|
+
|
|
+/* The default paths which get set are both bogus and oddly influenced
|
|
+ by <paths.h> and -D on the commands line. Just to be clear, we'll set
|
|
+ these explicitly. -ewt */
|
|
+#undef DEFAULT_LOGIN_PATH
|
|
+#undef DEFAULT_ROOT_LOGIN_PATH
|
|
+#define DEFAULT_LOGIN_PATH "/usr/local/bin:/bin:/usr/bin"
|
|
+#define DEFAULT_ROOT_LOGIN_PATH \
|
|
+ "/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin"
|
|
+
|
|
+/* The shell to run if none is given in the user's passwd entry. */
|
|
+#define DEFAULT_SHELL "/bin/sh"
|
|
+
|
|
+/* The user to become if none is specified. */
|
|
+#define DEFAULT_USER "root"
|
|
+
|
|
+char *crypt (char const *key, char const *salt);
|
|
+
|
|
+extern char **environ;
|
|
+
|
|
+static void run_shell (char const *, char const *, char **, size_t)
|
|
+ ATTRIBUTE_NORETURN;
|
|
+
|
|
+/* If true, pass the `-f' option to the subshell. */
|
|
+static bool fast_startup;
|
|
+
|
|
+/* If true, simulate a login instead of just starting a shell. */
|
|
+static bool simulate_login;
|
|
+
|
|
+/* If true, change some environment vars to indicate the user su'd to. */
|
|
+static bool change_environment;
|
|
+
|
|
+static struct option const longopts[] =
|
|
+{
|
|
+ {"command", required_argument, NULL, 'c'},
|
|
+ {"fast", no_argument, NULL, 'f'},
|
|
+ {"login", no_argument, NULL, 'l'},
|
|
+ {"preserve-environment", no_argument, NULL, 'p'},
|
|
+ {"shell", required_argument, NULL, 's'},
|
|
+ {GETOPT_HELP_OPTION_DECL},
|
|
+ {GETOPT_VERSION_OPTION_DECL},
|
|
+ {NULL, 0, NULL, 0}
|
|
+};
|
|
+
|
|
+/* Add NAME=VAL to the environment, checking for out of memory errors. */
|
|
+
|
|
+static void
|
|
+xsetenv (char const *name, char const *val)
|
|
+{
|
|
+ size_t namelen = strlen (name);
|
|
+ size_t vallen = strlen (val);
|
|
+ char *string = xmalloc (namelen + 1 + vallen + 1);
|
|
+ strcpy (string, name);
|
|
+ string[namelen] = '=';
|
|
+ strcpy (string + namelen + 1, val);
|
|
+ if (putenv (string) != 0)
|
|
+ xalloc_die ();
|
|
+}
|
|
+
|
|
+#if defined SYSLOG_SUCCESS || defined SYSLOG_FAILURE
|
|
+/* Log the fact that someone has run su to the user given by PW;
|
|
+ if SUCCESSFUL is true, they gave the correct password, etc. */
|
|
+
|
|
+static void
|
|
+log_su (struct passwd const *pw, bool successful)
|
|
+{
|
|
+ const char *new_user, *old_user, *tty;
|
|
+
|
|
+# ifndef SYSLOG_NON_ROOT
|
|
+ if (pw->pw_uid)
|
|
+ return;
|
|
+# endif
|
|
+ new_user = pw->pw_name;
|
|
+ /* The utmp entry (via getlogin) is probably the best way to identify
|
|
+ the user, especially if someone su's from a su-shell. */
|
|
+ old_user = getlogin ();
|
|
+ if (!old_user)
|
|
+ {
|
|
+ /* getlogin can fail -- usually due to lack of utmp entry.
|
|
+ Resort to getpwuid. */
|
|
+ struct passwd *pwd = getpwuid (getuid ());
|
|
+ old_user = (pwd ? pwd->pw_name : "");
|
|
+ }
|
|
+ tty = ttyname (STDERR_FILENO);
|
|
+ if (!tty)
|
|
+ tty = "none";
|
|
+ /* 4.2BSD openlog doesn't have the third parameter. */
|
|
+ openlog (last_component (program_name), 0
|
|
+# ifdef LOG_AUTH
|
|
+ , LOG_AUTH
|
|
+# endif
|
|
+ );
|
|
+ syslog (LOG_NOTICE,
|
|
+# ifdef SYSLOG_NON_ROOT
|
|
+ "%s(to %s) %s on %s",
|
|
+# else
|
|
+ "%s%s on %s",
|
|
+# endif
|
|
+ successful ? "" : "FAILED SU ",
|
|
+# ifdef SYSLOG_NON_ROOT
|
|
+ new_user,
|
|
+# endif
|
|
+ old_user, tty);
|
|
+ closelog ();
|
|
+}
|
|
+#endif
|
|
+
|
|
+/* Ask the user for a password.
|
|
+ Return true if the user gives the correct password for entry PW,
|
|
+ false if not. Return true without asking for a password if run by UID 0
|
|
+ or if PW has an empty password. */
|
|
+
|
|
+static bool
|
|
+correct_password (const struct passwd *pw)
|
|
+{
|
|
+ char *unencrypted, *encrypted, *correct;
|
|
+#if HAVE_GETSPNAM && HAVE_STRUCT_SPWD_SP_PWDP
|
|
+ /* Shadow passwd stuff for SVR3 and maybe other systems. */
|
|
+ struct spwd *sp = getspnam (pw->pw_name);
|
|
+
|
|
+ endspent ();
|
|
+ if (sp)
|
|
+ correct = sp->sp_pwdp;
|
|
+ else
|
|
+#endif
|
|
+ correct = pw->pw_passwd;
|
|
+
|
|
+ if (getuid () == 0 || !correct || correct[0] == '\0')
|
|
+ return true;
|
|
+
|
|
+ unencrypted = getpass (_("Password:"));
|
|
+ if (!unencrypted)
|
|
+ {
|
|
+ error (0, 0, _("getpass: cannot open /dev/tty"));
|
|
+ return false;
|
|
+ }
|
|
+ encrypted = crypt (unencrypted, correct);
|
|
+ memset (unencrypted, 0, strlen (unencrypted));
|
|
+ return STREQ (encrypted, correct);
|
|
+}
|
|
+
|
|
+/* Update `environ' for the new shell based on PW, with SHELL being
|
|
+ the value for the SHELL environment variable. */
|
|
+
|
|
+static void
|
|
+modify_environment (const struct passwd *pw, const char *shell)
|
|
+{
|
|
+ if (simulate_login)
|
|
+ {
|
|
+ /* Leave TERM unchanged. Set HOME, SHELL, USER, LOGNAME, PATH.
|
|
+ Unset all other environment variables. */
|
|
+ char const *term = getenv ("TERM");
|
|
+ if (term)
|
|
+ term = xstrdup (term);
|
|
+ environ = xmalloc ((6 + !!term) * sizeof (char *));
|
|
+ environ[0] = NULL;
|
|
+ if (term)
|
|
+ xsetenv ("TERM", term);
|
|
+ xsetenv ("HOME", pw->pw_dir);
|
|
+ xsetenv ("SHELL", shell);
|
|
+ xsetenv ("USER", pw->pw_name);
|
|
+ xsetenv ("LOGNAME", pw->pw_name);
|
|
+ xsetenv ("PATH", (pw->pw_uid
|
|
+ ? DEFAULT_LOGIN_PATH
|
|
+ : DEFAULT_ROOT_LOGIN_PATH));
|
|
+ }
|
|
+ else
|
|
+ {
|
|
+ /* Set HOME, SHELL, and if not becoming a super-user,
|
|
+ USER and LOGNAME. */
|
|
+ if (change_environment)
|
|
+ {
|
|
+ xsetenv ("HOME", pw->pw_dir);
|
|
+ xsetenv ("SHELL", shell);
|
|
+ if (pw->pw_uid)
|
|
+ {
|
|
+ xsetenv ("USER", pw->pw_name);
|
|
+ xsetenv ("LOGNAME", pw->pw_name);
|
|
+ }
|
|
+ }
|
|
+ }
|
|
+}
|
|
+
|
|
+/* Become the user and group(s) specified by PW. */
|
|
+
|
|
+static void
|
|
+change_identity (const struct passwd *pw)
|
|
+{
|
|
+#ifdef HAVE_INITGROUPS
|
|
+ errno = 0;
|
|
+ if (initgroups (pw->pw_name, pw->pw_gid) == -1)
|
|
+ error (EXIT_FAILURE, errno, _("cannot set groups"));
|
|
+ endgrent ();
|
|
+#endif
|
|
+ if (setgid (pw->pw_gid))
|
|
+ error (EXIT_FAILURE, errno, _("cannot set group id"));
|
|
+ if (setuid (pw->pw_uid))
|
|
+ error (EXIT_FAILURE, errno, _("cannot set user id"));
|
|
+}
|
|
+
|
|
+/* Run SHELL, or DEFAULT_SHELL if SHELL is empty.
|
|
+ If COMMAND is nonzero, pass it to the shell with the -c option.
|
|
+ Pass ADDITIONAL_ARGS to the shell as more arguments; there
|
|
+ are N_ADDITIONAL_ARGS extra arguments. */
|
|
+
|
|
+static void
|
|
+run_shell (char const *shell, char const *command, char **additional_args,
|
|
+ size_t n_additional_args)
|
|
+{
|
|
+ size_t n_args = 1 + fast_startup + 2 * !!command + n_additional_args + 1;
|
|
+ char const **args = xnmalloc (n_args, sizeof *args);
|
|
+ size_t argno = 1;
|
|
+
|
|
+ if (simulate_login)
|
|
+ {
|
|
+ char *arg0;
|
|
+ char *shell_basename;
|
|
+
|
|
+ shell_basename = last_component (shell);
|
|
+ arg0 = xmalloc (strlen (shell_basename) + 2);
|
|
+ arg0[0] = '-';
|
|
+ strcpy (arg0 + 1, shell_basename);
|
|
+ args[0] = arg0;
|
|
+ }
|
|
+ else
|
|
+ args[0] = last_component (shell);
|
|
+ if (fast_startup)
|
|
+ args[argno++] = "-f";
|
|
+ if (command)
|
|
+ {
|
|
+ args[argno++] = "-c";
|
|
+ args[argno++] = command;
|
|
+ }
|
|
+ memcpy (args + argno, additional_args, n_additional_args * sizeof *args);
|
|
+ args[argno + n_additional_args] = NULL;
|
|
+ execv (shell, (char **) args);
|
|
+
|
|
+ {
|
|
+ int exit_status = (errno == ENOENT ? EXIT_ENOENT : EXIT_CANNOT_INVOKE);
|
|
+ error (0, errno, "%s", shell);
|
|
+ exit (exit_status);
|
|
+ }
|
|
+}
|
|
+
|
|
+/* Return true if SHELL is a restricted shell (one not returned by
|
|
+ getusershell), else false, meaning it is a standard shell. */
|
|
+
|
|
+static bool
|
|
+restricted_shell (const char *shell)
|
|
+{
|
|
+ char *line;
|
|
+
|
|
+ setusershell ();
|
|
+ while ((line = getusershell ()) != NULL)
|
|
+ {
|
|
+ if (*line != '#' && STREQ (line, shell))
|
|
+ {
|
|
+ endusershell ();
|
|
+ return false;
|
|
+ }
|
|
+ }
|
|
+ endusershell ();
|
|
+ return true;
|
|
+}
|
|
+
|
|
+void
|
|
+usage (int status)
|
|
+{
|
|
+ if (status != EXIT_SUCCESS)
|
|
+ fprintf (stderr, _("Try `%s --help' for more information.\n"),
|
|
+ program_name);
|
|
+ else
|
|
+ {
|
|
+ printf (_("Usage: %s [OPTION]... [-] [USER [ARG]...]\n"), program_name);
|
|
+ fputs (_("\
|
|
+Change the effective user id and group id to that of USER.\n\
|
|
+\n\
|
|
+ -, -l, --login make the shell a login shell\n\
|
|
+ -c, --command=COMMAND pass a single COMMAND to the shell with -c\n\
|
|
+ -f, --fast pass -f to the shell (for csh or tcsh)\n\
|
|
+ -m, --preserve-environment do not reset environment variables\n\
|
|
+ -p same as -m\n\
|
|
+ -s, --shell=SHELL run SHELL if /etc/shells allows it\n\
|
|
+"), stdout);
|
|
+ fputs (HELP_OPTION_DESCRIPTION, stdout);
|
|
+ fputs (VERSION_OPTION_DESCRIPTION, stdout);
|
|
+ fputs (_("\
|
|
+\n\
|
|
+A mere - implies -l. If USER not given, assume root.\n\
|
|
+"), stdout);
|
|
+ emit_ancillary_info ();
|
|
+ }
|
|
+ exit (status);
|
|
+}
|
|
+
|
|
+int
|
|
+main (int argc, char **argv)
|
|
+{
|
|
+ int optc;
|
|
+ const char *new_user = DEFAULT_USER;
|
|
+ char *command = NULL;
|
|
+ char *shell = NULL;
|
|
+ struct passwd *pw;
|
|
+ struct passwd pw_copy;
|
|
+
|
|
+ initialize_main (&argc, &argv);
|
|
+ set_program_name (argv[0]);
|
|
+ setlocale (LC_ALL, "");
|
|
+ bindtextdomain (PACKAGE, LOCALEDIR);
|
|
+ textdomain (PACKAGE);
|
|
+
|
|
+ initialize_exit_failure (EXIT_FAILURE);
|
|
+ atexit (close_stdout);
|
|
+
|
|
+ fast_startup = false;
|
|
+ simulate_login = false;
|
|
+ change_environment = true;
|
|
+
|
|
+ while ((optc = getopt_long (argc, argv, "c:flmps:", longopts, NULL)) != -1)
|
|
+ {
|
|
+ switch (optc)
|
|
+ {
|
|
+ case 'c':
|
|
+ command = optarg;
|
|
+ break;
|
|
+
|
|
+ case 'f':
|
|
+ fast_startup = true;
|
|
+ break;
|
|
+
|
|
+ case 'l':
|
|
+ simulate_login = true;
|
|
+ break;
|
|
+
|
|
+ case 'm':
|
|
+ case 'p':
|
|
+ change_environment = false;
|
|
+ break;
|
|
+
|
|
+ case 's':
|
|
+ shell = optarg;
|
|
+ break;
|
|
+
|
|
+ case_GETOPT_HELP_CHAR;
|
|
+
|
|
+ case_GETOPT_VERSION_CHAR (PROGRAM_NAME, AUTHORS);
|
|
+
|
|
+ default:
|
|
+ usage (EXIT_FAILURE);
|
|
+ }
|
|
+ }
|
|
+
|
|
+ if (optind < argc && STREQ (argv[optind], "-"))
|
|
+ {
|
|
+ simulate_login = true;
|
|
+ ++optind;
|
|
+ }
|
|
+ if (optind < argc)
|
|
+ new_user = argv[optind++];
|
|
+
|
|
+ pw = getpwnam (new_user);
|
|
+ if (! (pw && pw->pw_name && pw->pw_name[0] && pw->pw_dir && pw->pw_dir[0]
|
|
+ && pw->pw_passwd))
|
|
+ error (EXIT_FAILURE, 0, _("user %s does not exist"), new_user);
|
|
+
|
|
+ /* Make a copy of the password information and point pw at the local
|
|
+ copy instead. Otherwise, some systems (e.g. GNU/Linux) would clobber
|
|
+ the static data through the getlogin call from log_su.
|
|
+ Also, make sure pw->pw_shell is a nonempty string.
|
|
+ It may be NULL when NEW_USER is a username that is retrieved via NIS (YP),
|
|
+ but that doesn't have a default shell listed. */
|
|
+ pw_copy = *pw;
|
|
+ pw = &pw_copy;
|
|
+ pw->pw_name = xstrdup (pw->pw_name);
|
|
+ pw->pw_passwd = xstrdup (pw->pw_passwd);
|
|
+ pw->pw_dir = xstrdup (pw->pw_dir);
|
|
+ pw->pw_shell = xstrdup (pw->pw_shell && pw->pw_shell[0]
|
|
+ ? pw->pw_shell
|
|
+ : DEFAULT_SHELL);
|
|
+ endpwent ();
|
|
+
|
|
+ if (!correct_password (pw))
|
|
+ {
|
|
+#ifdef SYSLOG_FAILURE
|
|
+ log_su (pw, false);
|
|
+#endif
|
|
+ error (EXIT_FAILURE, 0, _("incorrect password"));
|
|
+ }
|
|
+#ifdef SYSLOG_SUCCESS
|
|
+ else
|
|
+ {
|
|
+ log_su (pw, true);
|
|
+ }
|
|
+#endif
|
|
+
|
|
+ if (!shell && !change_environment)
|
|
+ shell = getenv ("SHELL");
|
|
+ if (shell && getuid () != 0 && restricted_shell (pw->pw_shell))
|
|
+ {
|
|
+ /* The user being su'd to has a nonstandard shell, and so is
|
|
+ probably a uucp account or has restricted access. Don't
|
|
+ compromise the account by allowing access with a standard
|
|
+ shell. */
|
|
+ error (0, 0, _("using restricted shell %s"), pw->pw_shell);
|
|
+ shell = NULL;
|
|
+ }
|
|
+ shell = xstrdup (shell ? shell : pw->pw_shell);
|
|
+ modify_environment (pw, shell);
|
|
+
|
|
+ change_identity (pw);
|
|
+ if (simulate_login && chdir (pw->pw_dir) != 0)
|
|
+ error (0, errno, _("warning: cannot change directory to %s"), pw->pw_dir);
|
|
+
|
|
+ run_shell (shell, command, argv + optind, MAX (0, argc - optind));
|
|
+}
|