diff options
author | Jim Meyering <jim@meyering.net> | 1994-10-01 02:22:07 +0000 |
---|---|---|
committer | Jim Meyering <jim@meyering.net> | 1994-10-01 02:22:07 +0000 |
commit | c8131583acd9716253b98a976c717df28c5a3874 (patch) | |
tree | 13fd3b57970136b36f5b8d844d5f0a86e00e4bc8 | |
parent | 10c7a38d84908e603d971f8a0d030f90760f2894 (diff) | |
download | coreutils-c8131583acd9716253b98a976c717df28c5a3874.tar.xz |
Update from Karl.
-rw-r--r-- | doc/sh-utils.texi | 248 |
1 files changed, 144 insertions, 104 deletions
diff --git a/doc/sh-utils.texi b/doc/sh-utils.texi index 7a33e40ad..1aa66b8b9 100644 --- a/doc/sh-utils.texi +++ b/doc/sh-utils.texi @@ -21,63 +21,35 @@ @ifinfo @format START-INFO-DIR-ENTRY -* Shell utilities: (sh-utils). GNU shell utilities. -* basename invocation: (sh-utils)basename invocation. - Strip directory and suffix from a file name. -* date invocation: (sh-utils)date invocation. - Print or set system date and time. -* dirname invocation: (sh-utils)dirname invocation. - Strip non-directory suffix from a file name. -* echo invocation: (sh-utils)echo invocation. - Print a line of text. -* env invocation: (sh-utils)env invocation. - Modify the environment. -* expr invocation: (sh-utils)expr invocation. - Evaluate expressions. -* false invocation: (sh-utils)false invocation. - Do nothing, unsuccessfully. -* groups invocation: (sh-utils)groups invocation. - Print group names a user is in. -* hostname invocation: (sh-utils)hostname invocation. - Print or set system name. -* id invocation: (sh-utils)id invocation. - Print real and effective uid and gid. -* logname invocation: (sh-utils)logname invocation. - Print current login name. -* nice invocation: (sh-utils)nice invocation. - Modify the scheduling priority. -* pathchk invocation: (sh-utils)pathchk invocation. - Check file name portability. -* printenv invocation: (sh-utils)printenv invocation. - Print all or part of the environment. -* printf invocation: (sh-utils)printf invocation. - Format and print data. -* pwd invocation: (sh-utils)pwd invocation. - Print working directory. -* sleep invocation: (sh-utils)sleep invocation. - Delay for a specified time. -* stty invocation: (sh-utils)stty invocation. - Print or change terminal characteristics. -* su invocation: (sh-utils)su invocation. - Modify the user and group id. -* tee invocation: (sh-utils)tee invocation. - Redirect output to multiple files. -* test invocation: (sh-utils)test invocation. - Check file types and compare values. -* true invocation: (sh-utils)true invocation. - Do nothing, successfully. -* tty invocation: (sh-utils)tty invocation. - Print or change terminal characteristics. -* uname invocation: (sh-utils)uname invocation. - Print system information. -* users invocation: (sh-utils)users invocation. - Print login names of users currently logged in. -* who invocation: (sh-utils)who invocation. - Print who is currently logged in. -* whoami invocation: (sh-utils)whoami invocation. - Print effective user id. -* yes invocation: (sh-utils)yes invocation. - Print a string until interrupted. +* Shell utilities: (sh-utils). GNU shell utilities. +* basename: (sh-utils)basename invocation. Strip directory and suffix. +* date: (sh-utils)date invocation. Print/set system date and time. +* dirname: (sh-utils)dirname invocation. Strip non-directory suffix. +* echo: (sh-utils)echo invocation. Print a line of text. +* env: (sh-utils)env invocation. Modify the environment. +* expr: (sh-utils)expr invocation. Evaluate expressions. +* false: (sh-utils)false invocation. Do nothing, unsuccessfully. +* groups: (sh-utils)groups invocation. Print group names a user is in. +* hostname: (sh-utils)hostname invocation. Print or set system name. +* id: (sh-utils)id invocation. Print real/effective uid/gid. +* logname: (sh-utils)logname invocation. Print current login name. +* nice: (sh-utils)nice invocation. Modify scheduling priority. +* pathchk: (sh-utils)pathchk invocation. Check file name portability. +* printenv: (sh-utils)printenv invocation. Print environment variables. +* printf: (sh-utils)printf invocation. Format and print data. +* pwd: (sh-utils)pwd invocation. Print working directory. +* sleep: (sh-utils)sleep invocation. Delay for a specified time. +* stty: (sh-utils)stty invocation. Print/change terminal settings. +* su: (sh-utils)su invocation. Modify user and group id. +* tee: (sh-utils)tee invocation. Redirect to multiple files. +* test: (sh-utils)test invocation. File/string tests. +* true: (sh-utils)true invocation. Do nothing, successfully. +* tty: (sh-utils)tty invocation. Print terminal name. +* uname: (sh-utils)uname invocation. Print system information. +* users: (sh-utils)users invocation. Print current user names. +* who: (sh-utils)who invocation. Print who is logged in. +* whoami: (sh-utils)whoami invocation. Print effective user id. +* yes: (sh-utils)yes invocation. Print a string indefinitely. END-INFO-DIR-ENTRY @end format @end ifinfo @@ -112,8 +84,8 @@ by the Foundation. @titlepage @title GNU sh-utils, version @value{VERSION} @subtitle A set of shell utilities -@subtitle for version @value{VERSION}, @value{RELEASE_DATE} -@author Jim Meyering +@subtitle for version @value{VERSION}, @value{RELEASE-DATE} +@author David MacKenzie et al. @page @vskip 0pt plus 1filll @@ -143,14 +115,10 @@ by the Foundation. @cindex utilities for shell programming This manual minimally documents version @value{VERSION} of the GNU shell -utilities. The @code{stty} section, in particular, needs substantial -reorganization and additional explanatory text before it will be up to -the standard of other GNU manuals. - -@cindex POSIX.2 -The GNU shell utilities are mostly compatible with the POSIX.2 standard. +utilities. See the introduction for caveats. @menu +* Introduction:: Caveats, overview, and author. * Common options:: Common options. * Printing text:: echo printf yes * Conditions:: false true test expr @@ -166,6 +134,39 @@ The GNU shell utilities are mostly compatible with the POSIX.2 standard. @end ifinfo +@node Introduction +@chapter Introduction + +@cindex introduction + +First of all, this manual is incomplete. The @code{stty} section, in +particular, needs substantial reorganization and additional explanatory +text before it will be up to the standard of other GNU manuals. +Explanatory text in general is lacking; the manual presently assumes you +pretty much know what to do, and just need to be reminded of how. Thus, +if you are interested, please get involved in improving this manual. +The entire GNU community will benefit. + +Some of these programs are useful only when writing shell scripts; +utilities like these are, in fact, the ``language'' of shell scripts (to +a great extent). Others are occasionally useful interactively. + +@cindex POSIX.2 +The GNU shell utilities are mostly compatible with the POSIX.2 standard. + +Please report bugs to @samp{bug-gnu-utils@@prep.ai.mit.edu}. Remember +to include the version number, machine architecture, input files, and +any other information needed to reproduce the bug. @xref{Bugs, , , gcc, +GNU CC}. + +This manual is based on the Unix man pages in the distribution, which +were originally written by David MacKenzie and updated by Jim Meyering. +Francois Pinard did the initial conversion to Texinfo format. Karl +Berry did the indexing, some reorganization, and editing of the results. +Richard Stallman contributed his usual invaluable insights to the +overall process. + + @node Common options @chapter Common options @@ -312,8 +313,8 @@ The only options are a lone @samp{--help} or 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. -The only options are a lone @samp{--help} or -@samp{--version}. @xref{Common options}. +The only options are a lone @samp{--help} or @samp{--version}. +@xref{Common options}. @node Conditions @@ -1046,7 +1047,7 @@ 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 all or part of the environment. +* printenv invocation:: Print environment variables. * tty invocation:: Print file name of terminal on standard input. @end menu @@ -1695,11 +1696,11 @@ of: 0 50 75 110 134 134.5 150 200 300 600 1200 1800 2400 4800 9600 @node printenv invocation -@section @code{printenv}: Print all or part of the environment +@section @code{printenv}: Print all or some environment variables @pindex printenv -@cindex printing all or part of the environment -@cindex environment, printing all or part of +@cindex printing all or some environment variables +@cindex environment variables, printing Synopsis: @@ -1707,12 +1708,12 @@ Synopsis: printenv [ @var{option} ] [ @var{variable} ]@dots{} @end example -If no @var{variable}s are specified, @code{printenv} prints the entire -environment. Otherwise, it prints the value of each @var{variable} that -is set, and nothing for those that are not set. +If no @var{variable}s are specified, @code{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 @samp{--help} or -@samp{--version}. @xref{Common options}. +The only options are a lone @samp{--help} or @samp{--version}. +@xref{Common options}. @cindex exit status of @code{printenv} Exit status: @@ -2254,16 +2255,33 @@ The program accepts the following options. Also see @ref{Common options}. @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} +@flindex getdate.y Display the time and date specified in @var{datestr} instead of the -current time and date. @var{datestr} can be in almost any common format. +current time and date. @var{datestr} can be in almost any common +format. It can contain month names, timezones, @samp{am} and @samp{pm}, +@samp{yesterday}, @samp{ago}, @samp{next}, etc. The source file +@file{getdate.y} implements this parsing for all GNU routines; we need +precise documentation! + +@item -f @var{datefile} +@itemx --file=@var{datefile} +@opindex -f +@opindex --file +Parse each line in @var{datefile} as with @samp{-d} and display the +resulting time and date. 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 @code{date} executable many times can +be considerable. @item -s @var{datestr} @itemx --set=@var{datestr} @opindex -s @opindex --set -Set the time and date to @var{datestr}, which can be in almost any -common format. It can contain month names, timezones, @samp{am} and -@samp{pm}, @samp{yesterday}, @samp{ago}, etc. +Set the time and date to @var{datestr}, See @samp{-d} above. @item -u @itemx --utc @@ -2284,12 +2302,14 @@ in local (wall clock) time. @cindex examples of @code{date} -Here are a few examples. +Here are a few examples. Also see the documentation for the @samp{-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 @@ -2314,21 +2334,21 @@ date '+%B %d' 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 1-may '+%B %d'} will print @samp{May 01}. +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 (GNU extension) @code{-} modifier to suppress the padding altogether. @example -date -d=1-may '+%B %-d' +date -d=1may '+%B %-d' @end example @item To print the current date and time in the format required by many non-GNU versions of @code{date} when setting the system clock: @example -date +%m%d%H%M%Y.%s +date +%m%d%H%M%Y.%S @end example @item @@ -2460,15 +2480,15 @@ different than the current one: a modified environment, as a different user, etc. @menu -* env invocation:: Modify the environment. -* nice invocation:: Modify the scheduling priority. +* env invocation:: Modify environment variables. +* nice invocation:: Modify scheduling priority. * nohup invocation:: Immunize to hangups. -* su invocation:: Modify the user and group id. +* su invocation:: Modify user and group id. @end menu @node env invocation -@section @code{env}: Run a program in a modified environment +@section @code{env}: Run a command in a modified environment @pindex env @cindex environment, running a program in a modified @@ -2524,7 +2544,7 @@ Start with an empty environment, ignoring the inherited environment. @node nice invocation -@section @code{nice}: Run a program with modified scheduling priority +@section @code{nice}: Run a command with modified scheduling priority @pindex nice @cindex modifying scheduling priority @@ -2566,7 +2586,7 @@ Add @var{adjustment} instead of 10 to the command's priority. @node nohup invocation -@section @code{nohup}: Run a program immune to hangups +@section @code{nohup}: Run a command immune to hangups @pindex nohup @cindex hangups, immunity to @@ -2604,7 +2624,7 @@ options}. @node su invocation -@section @code{su}: Run a shell with substitute user and group id +@section @code{su}: Run a command with substitute user and group id @pindex su @cindex substitute user and group IDs @@ -2642,25 +2662,19 @@ from the password entry for @var{user}, and if @var{user} is not the super-user, sets @code{USER} and @code{LOGNAME} to @var{user}. By default, the shell is not a login shell. -If one or more @var{arg}s are given, they are passed as additional -arguments to the shell. +Any additional @var{arg}s are passed as additional arguments to the +shell. @cindex @samp{-su} -@code{su} does not handle @file{/bin/sh} or any other shells specially +GNU @code{su} does not treat @file{/bin/sh} or any other shells specially (e.g., by setting @code{argv[0]} to @samp{-su}, passing @code{-c} only to certain shells, etc.). @findex syslog -On systems that have @code{syslog}, @code{su} can be compiled to report -failed, and optionally successful, @code{su} attempts using -@code{syslog}. - -@cindex wheel group, not supported -@cindex group wheel, not supported -@cindex fascism -This program does not support a ``wheel group'' that restricts who -can @code{su} to super-user accounts, because that can help fascist -system administrators hold unwarranted power over other users. +@code{su} can optionally be compiled to use @code{syslog} to report +failed, and optionally successful, @code{su} attempts. (If the system +supports @code{syslog}.) However, GNU @code{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}. @@ -2731,6 +2745,32 @@ shell is restricted (see @samp{-m} just above). @end table +@cindex wheel group, not supported +@cindex group wheel, not supported +@cindex fascism +@heading Why GNU @code{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 +@code{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 Delaying @chapter Delaying |