@c $Id: basic-commands.texinfo,v 1.30 2002/01/09 16:57:30 m Exp m $
@node Basics, Shell, Intro, Getting Started
@comment  node-name,  next,  previous,  up
@chapter What Every Linux User Knows
@cindex what every Linux user knows
@cindex basic commands and concepts

@noindent
This chapter concerns those concepts and commands that every Linux user
knows---how to start and stop the system, log in and out from it, change
your password, see what is happening on the system, and use the system
help facilities. Mastery of these basic concepts is essential for using
Linux with any degree of success.

Some of these recipes make reference to files and directories; these
concepts are explained in @ref{Files and Directories, , Files and
Directories}.

@menu
* Power::                       How to start and stop the system.
* Accounts::                    Using your account to access the system.
* Console::                     The basics of the Linux console.
* Commands::                    Commands and how to run them.
* Password::                    How to change your password.
* Users::                       Looking at the system's users.
* Processes::                   Looking at system processes.
* Help::                        System help facilities.
@end menu


@node Power, Accounts, Basics, Basics
@comment  node-name,  next,  previous,  up
@section Controlling Power to the System
@cindex controlling power to the system
@cindex power, controlling to the system
@cindex system, controlling power to the

@noindent
These recipes show how to start and stop power to the system---how to
turn it on and turn it off. It's more than just pressing the button on
the case; in particular, there is a right way to turn off the system,
and doing it wrong can result in losing some of your work. Fortunately,
there isn't any black magic involved, as we soon shall see---properly
shutting down the system is easy!

@menu
* Startup::                     Booting up the system.
* Turning Off::                 Turning off the system.
@end menu


@node Startup, Turning Off, Power, Power
@comment  node-name,  next,  previous,  up
@subsection Powering Up the System
@cindex powering up the system
@cindex system, powering up the
@cindex booting the system

@noindent
The first thing you do to begin using the system is start power to it.
To power up the system, just turn it on. This is called @dfn{booting}
the system.

As the Linux kernel boots there will be many messages on the
screen. After a while, the system will display a @code{login:}
prompt. You can now log in. @xref{Login, , Logging In to the System}.

Some systems are configured to start @code{xdm} at boot time
(@pxref{Starting X, , Starting X}). If your system is configured like
this, instead of the @code{login:} prompt described above, you'll see a
graphical screen with a box in the middle containing both @code{login:}
and @code{Password:} prompts. Type @kbd{@key{CTRL}-@key{ALT}-@key{F1}} to
switch to the first virtual console, where you can log in to the system
in the usual way (@pxref{Console, , Console Basics}).


@node Turning Off, , Startup, Power
@comment  node-name,  next,  previous,  up
@subsection Turning Off the System
@cindex turning off the system
@cindex system, turning off the 

@noindent
You can't just flip the power switch when you are done using the
computer, because Linux is constantly writing data to disk. (It also
keeps data in memory, even when it may have appeared to have written
that data to disk.) Simply turning off the power could result in the
loss or corruption of some of your work.

The following describes a method of turning off the system that can be
done by a normal user; the traditional way of shutting down can only be
performed by the superuser, and is described in @ref{System Shutdown, ,
Shutting Down the System}.

To turn off a single user system, first log out of all consoles
(discussed in @ref{Console, , Console Basics}). Then, type
@kbd{@key{CTRL}-@key{ALT}-@key{DEL}} (press and hold these three keys at
once).@footnote{If you keyboard has two @key{ALT} and @key{CTRL} keys,
use the @emph{left} set of these keys.}

The system will print some messages as it shuts down, and when you see
the line, @samp{Rebooting...}, it's safe to turn the power to machine
off.

@sp .25
@noindent
@strong{NOTE:} You don't want to wait @emph{too} long after you see this
message; if left untouched, the system will reboot and you'll be back to
the beginning!


@node Accounts, Console, Power, Basics
@comment  node-name,  next,  previous,  up
@section Accounts and Privileges
@cindex accounts and privileges
@cindex privileges, user
@cindex user privileges
@cindex user accounts
@cindex superuser
@cindex root
@cindex password, choosing a
@cindex username
@cindex Hitchcock, Alfred
@cindex @cite{39 Steps, The}

@noindent
Linux is a multi-user system, meaning that many users can use one Linux
system simultaneously, from different terminals. So to avoid confusion
(and to maintain a semblance of privacy), each user's workspace must be
kept separate from the others.

Even if a particular Linux system is a stand-alone personal computer
with no other terminals physically connected to it, it can be shared by
different people at different times, making the separation of user
workspace still a valid issue.

This separation is accomplished by giving each individual user an
@dfn{account} on the system. You need an account in order to use the
system; with an account you are issued an individual workspace to use,
and a unique @dfn{username} that identifies you to the system and to
other users. It is the name that the system (and those who use it) will
then forever know you as; it's a single word, in all lowercase letters.

During the installation process, the system administrator should have
created an account for you. (The system administrator has a special
account whose username is @code{root}; this account has total access to
the entire system, so it is often called the @dfn{superuser}.)

Until the mid-1990s it was widely common for usernames to be the first
letter of your first name followed by your entire surname, up to 12
characters total. So for example, user Samuel Clemens would have a
username of @code{sclemens} by this convention; this, however, is not a
hard and fast rule, especially on home systems where you may be the only
user. Sometimes, a middle initial may be used (``@code{dkjohnson}''), or
sometimes even nicknames or initials are used (``@code{zenboy},''
``@code{xibo}''). But whatever username you pick for yourself, make sure
it's one you can live with, and one you can stand being called by both
the system and other users (your username also becomes part of your
email address, as we'll see in @ref{Email, , Email}).

In addition to your username, you should also have a @dfn{password} that
you can keep secret so that only you can use your account. Good
passwords are strings of text that nobody else is likely to guess (i.e.,
not obvious words like @samp{secret}, or identifying names like
@samp{Ruski}, if that happens to be your pet cat). A good password is 
one that is highly memorable to you so that you don't have to write it
down, but is complex enough in construction so that anyone else couldn't
ever guess it. For example, @samp{t39sAH} might be a
fine password for someone whose first date was to see the movie @cite{The 39
Steps} directed by Alfred Hitchcock. 

@sp .25
@noindent
@strong{NOTE:} While usernames are always in lowercase, passwords are
case sensitive; the passwords @samp{Secret}, @samp{secret}, and
@samp{SECRET} are all considered different. 

@menu
* Login::                       How to log in to the system.
* Logout::                      How to log out of the system.
@end menu


@node Login, Logout, Accounts, Accounts
@comment  node-name,  next,  previous,  up
@subsection Logging In to the System
@cindex logging in to the system
@cindex system, logging in to the
@cindex message of the day
@cindex motd
@cindex FQDN
@cindex host
@cindex hostname
@cindex issue
@cindex tty
@cindex teletype

@noindent
To begin a session on a Linux system, you need to @dfn{log in}. Do this
by entering your username at the @code{login:} prompt on your terminal,
and then entering your password when asked.

The @code{login:} prompt appears on the terminal after the system
boots. If your system is configured to start the X Window System at boot
time, you'll be presented with an X login screen instead of the standard
login prompt. If that happens, press @key{CTRL}-@key{ALT}-@key{F1} to
switch to the text login screen; this is explained further in
@ref{Console, , Console Basics}.

A typical @code{login:} prompt looks like this:

@example
@cartouche

Debian GNU/Linux 2.2 bardo tty1

bardo login:
@end cartouche
@end example

Every Linux system has its own name, called the system's @dfn{hostname};
a Linux system is sometimes called a @dfn{host}, and it identifies
itself with its hostname at the @code{login:} prompt. It's important to
name your system---like a username for a user account, a hostname gives
name to the system you are using (and it becomes especially important
when putting the system on a network). The system administrator usually
names the system when it is being initially configured (the hostname can
always be changed later; its name is kept in the file
@file{/etc/hostname}). Like usernames, hostnames are one word in all
lowercase letters. People usually give their system a name they like,
such as @code{darkstar} or @code{shiva}.

In this example, @samp{bardo} is the hostname of this particular Linux
system.

The name of the terminal you are connecting from is displayed just after
the hostname. In this example, the terminal is @samp{tty1}, which means
that this is the first terminal on this particular
system. (Incidentally, @samp{tty} is short for ``teletype,'' which
historically was the kind of terminal hardware that most Unix-based
systems used by default.)

To log in to the system, type your username (followed by @key{RET}) at
the @code{login:} prompt, and then type your password when asked (also
followed by @key{RET}); for security purposes, your password is not
displayed on the screen when you type it.

@itemize @bullet
@item
To log in to the system with a username of @samp{kurt} and a password
of @samp{empathy}, type:
@end itemize

@example
@cartouche

Debian GNU/Linux 2.2 bardo tty1

bardo login: @kbd{kurt @key{RET}}
Password: @kbd{@var{empathy} @key{RET}}
Linux bardo 2.0.30 #1 Tue Jul 29 10:01:26 EDT 1997 i586 unknown

Copyright (C) 1993-1998 Software in the Public Interest, and others

Most of the programs included with the Debian Linux system are
freely redistributable; the exact distribution terms for each
program are described in the individual files in 
/usr/doc/*/copyright

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Tue Apr  5 12:03:47 on tty1.
No mail.
~ $
@end cartouche
@end example

Once you've entered your username and password, you are ``logged in'' to
the system. You can then use the system and run commands.

As soon as you log in, the system displays the contents of
@file{/etc/motd}, the ``Message of the Day'' file. The system then
displays the time and date of your last login, and reports whether or
not you have electronic mail waiting for you (@pxref{Email, ,
Email}). Finally, the system puts you in a @dfn{shell}---the environment
in which you interact with the system and give it commands. Use of the
default shell on most Linux systems, @code{bash}, is discussed
in @ref{Shell, , The Shell}.

The dollar sign (@samp{$}) displayed to the left of the cursor is called
the @dfn{shell prompt}; it means that the system is ready and waiting
for input. (You can change this prompt to any text of your liking; to
learn how, @pxref{Shell Prompt, , Changing the Shell Prompt}.) By
default, the shell prompt includes the name of the current directory,
which it places to the left of the @samp{$} character. The tilde
character (@samp{~}), is a shell symbol that denotes the user's home
directory---when you log in, you are in your home directory (these terms
are defined in @ref{Files and Directories, , Files and Directories}).


@node Logout, , Login, Accounts
@comment  node-name,  next,  previous,  up
@subsection Logging Out of the System
@cindex logging out of the system
@cindex system, logging out of the
@pindex logout

@noindent
To end your session on the system, type @kbd{logout} at the shell
prompt. This command logs you out of the system, and a new @code{login:}
prompt appears on your terminal.

@itemize @bullet
@item
To log out of the system, type:

@example
@cartouche
$ @kbd{logout @key{RET}}


Debian GNU/Linux 2.2 bardo tty1

bardo login:
@end cartouche
@end example
@end itemize

What works equally well to typing the @code{logout} command is to just
type @kbd{C-d} (hold down @key{CTRL} and press @key{D}). You don't even
have to type @key{RET} afterwards. Many users prefer this quick
shortcut.

Logging out of the system frees the terminal you were using---and
ensures that nobody can access your account from this terminal.

If you are the only person using your system and have just ended a
session by logging out, you might want to power down the system.
@xref{Turning Off, , Turning Off the System}, earlier in this chapter.


@node Console, Commands, Accounts, Basics
@comment  node-name,  next,  previous,  up
@section Console Basics
@cindex console basics
@cindex virtual consoles
@cindex terminals

@noindent
A Linux @dfn{terminal} is a place to put input and get output from the
system, and usually has at least a keyboard and monitor. 

When you access a Linux system by the keyboard and monitor that are
directly connected to it, you are said to be using the @dfn{console}
terminal. (Linux systems can be accessed in other ways, such as through
a network or via another terminal connected to a serial line;
@pxref{Communications, , Communications}).

Linux systems feature @dfn{virtual consoles}, which act as separate
console displays that can run separate login sessions, but are
accessed from the same physical console terminal. Linux systems are
configured to have seven virtual consoles by default. When you are at
the console terminal, you can switch between virtual consoles at any
time, and you can log in and use the system from several virtual
consoles at once.

The following recipes explain the basic things you will need to do with
virtual consoles. 

@menu
* Switching Consoles::          Switching between consoles.
* Scrolling Consoles::          Scrolling the text on the screen.
* Console Commands::            Keystrokes for manipulating the console.
@end menu


@node Switching Consoles, Scrolling Consoles, Console, Console
@comment  node-name,  next,  previous,  up
@subsection Switching between Consoles
@cindex switching between consoles
@cindex consoles, switching between

@noindent
To switch to a different virtual console, press @key{ALT}-@key{F@var{n}},
where @var{n} is the number of the console to switch to.

@itemize @bullet
@item
To switch to the fourth virtual console, press @key{ALT}-@key{F4}.
@end itemize

This command switches to the fourth virtual console, denoted by
@samp{tty4}:

@example
@cartouche

Debian GNU/Linux 2.2 bardo tty4

bardo login:
@end cartouche
@end example

You can also cycle through the different virtual consoles with the left
and right arrow keys. To switch to the next-lowest virtual console (or
wrap around to the highest virtual console, if you're at the first
virtual console), press @key{ALT}-@key{@math{@leftarrow}}. To switch to
the next-highest virtual console, press
@key{ALT}-@key{@math{@rightarrow}}.
@ifinfo
[GNU INFO BUG: any <> in the preceding line should be the one of the cursor arrow keys.]
@end ifinfo

@itemize @bullet
@item
To switch from the fourth to the third virtual console, press:

@example
@kbd{@key{ALT}-@key{@math{@leftarrow}}}
@ifinfo
[GNU INFO BUG: any <> in the preceding line should be the one of the cursor arrow keys.]
@end ifinfo
@end example
@end itemize

This keystroke switches to the third virtual console, @samp{tty3}:

@example
@cartouche

Debian GNU/Linux 2.2 bardo tty3

bardo login:
@end cartouche
@end example

The seventh virtual console is reserved for the X Window System. If X is
installed, this virtual terminal will never show a @code{login:} prompt,
but when you are using X, this is where your X session appears. If your
system is configured to start X immediately, this virtual console will
show an X login screen.

You can switch to a virtual console from the X Window System using
@key{CTRL} in conjunction with the usual @key{ALT} and function
keys. This is the only console manipulation keystroke that works in X.

@itemize @bullet
@item
To switch from X to the first virtual console, press:

@example
@kbd{@key{CTRL}-@key{ALT}-@key{F1}}
@end example
@end itemize


@node Scrolling Consoles, Console Commands, Switching Consoles, Console
@comment  node-name,  next,  previous,  up
@subsection Scrolling the Console Text
@cindex scrolling the console text
@cindex console text, scrolling
@cindex text, scrolling the console

@noindent
When you are logged in at a virtual console, new lines of text appear at
the bottom of the console screen, while older lines of text scroll off
the top of the screen.

@itemize @bullet
@item
To view this older text, press @key{SHIFT}-@key{PgUp}
to scroll back through it.

@item
Once you have scrolled back, press @key{SHIFT}-@key{PgDn} to scroll
@emph{forward} through the text toward the most recent text displayed on
the console.
@end itemize

The amount of text you can scroll back through depends on system memory.

@sp .25
@noindent
@strong{NOTE:} This technique is for scrolling through text displayed in
your shell session (@pxref{Shell, , The Shell}). It does not work for
scrolling through text in a tool or application in the console---in
other words, you can't use this technique to scroll through text that is
displayed by a tool for perusing text files. To scroll through text in
an application, use its own facilities for scrolling, if it has any.


@node Console Commands, , Scrolling Consoles, Console
@comment  node-name,  next,  previous,  up
@subsection Keys for Console Manipulation
@cindex keys for console manipulation
@cindex console manipulation, keys for 

@noindent
Some keystrokes for manipulating the console display, including those
for switching between virtual consoles, are described below. It's a good
idea to experiment with these commands until you are comfortable with
them, because knowing how to use virtual consoles is basic to using
Linux.

@multitable @columnfractions .30 .70
@item @sc{Keystroke}
@tab @sc{Description}
@item @key{ALT}-@key{F@var{n}}
@tab Switch to virtual console @var{n}, where @var{n} is a number from 1
to 7 (the default maximum).

@item @key{CTRL}-@key{ALT}-@key{F@var{n}}
@tab When in X, switch to virtual console @var{n}, where @var{n} is a
number from 1 to 6.

@item @key{ALT}-@key{@math{@leftarrow}}
@tab Switch to the next-lowest virtual console. For example, typing this
while in virtual console 4 switches to virtual console 3. Pressing this
keystroke in the lowest console wraps around to the highest console.
@ifinfo
[GNU INFO BUG: any <> in the preceding line should be the one of the cursor arrow keys.]
@end ifinfo

@item @key{ALT}-@key{@math{@rightarrow}}
@tab Switch to the next-highest virtual console.  For example, typing
this while in virtual console 4 switches to virtual console 5. Pressing
this keystroke in the highest console wraps around to the lowest
console.
@ifinfo
[GNU INFO BUG: any <> in the preceding line should be the one of the cursor arrow keys.]
@end ifinfo

@item @key{SHIFT}-@key{PgUp}
@tab Scroll back one screen to view previously displayed text.

@item @key{SHIFT}-@key{PgDn}
@tab When viewing previously displayed text, scroll forward one screen.
@end multitable


@node Commands, Password, Console, Basics
@comment  node-name,  next,  previous,  up
@section Running a Command
@cindex running a command
@cindex command, running a
@cindex options, long-style
@cindex tools
@cindex applications
@cindex arguments
@cindex flags
@pindex hostname

@noindent
A @dfn{tool} is a software program that performs a certain
function---usually a specialized, simple task. For example, the
@code{hostname} tool outputs the system's hostname, and the @code{who}
tool outputs a listing of the users who are currently logged in. An
@dfn{application} is the name given to larger, usually interactive,
programs for completing broader kinds of tasks---such as programs for
image editing or word processing.

A tool or application may take any number of @dfn{options} (sometimes
called ``flags''), which specify a change in its default behavior. It
may also take @dfn{arguments}, which specify a file or some other text
to operate on. Arguments are usually specified after any options.

A @dfn{command} is the name of a tool or application along with the
options and arguments you want to use, if any. Since typing the name of
a tool itself is often sufficient to accomplish a desired task, tools
alone are often called commands.

Commands are case sensitive; the names of tools and applications
are usually in all lowercase letters.

To run (or ``execute'') a tool or application without giving any options
or arguments, type its name at a shell prompt followed by @key{RET}.

@itemize @bullet
@item
To run the @code{hostname} tool, type:

@example
@cartouche
$ @kbd{hostname @key{RET}}
bardo
$
@end cartouche
@end example
@end itemize

The hostname of the system in the example is @samp{bardo}.

Options always begin with a hyphen character, @samp{-}, which is usually
followed by one alphanumeric character. To include an option in a
command, follow the name of the tool or application with the option.
Always separate the tool name, each option, and each argument with a
space character.

@dfn{Long-style} options (sometimes called ``GNU-style'' options) begin
with two hyphen characters (@samp{--}) and are usually one English word.

For example, many tools have an option, @samp{--version}, to output the
version number of the tool. (Many tools also have a @samp{--help}
option, which outputs a list of options the tool takes; @pxref{Usage
Help, , Listing the Usage of a Tool}.)

@itemize @bullet
@item
To output the version of the @code{hostname} tool, type:

@example
@cartouche
$ @kbd{hostname --version @key{RET}}
hostname 2.10
$
@end cartouche
@end example
@end itemize

This command outputs the text @samp{hostname 2.10}, indicating that this
is version 2.10 of the @code{hostname} tool.

Sometimes, an option itself may may take an argument. For example,
@code{hostname} has an option for specifying a file name to use to read
the hostname from, @samp{-F}; it takes as an argument the name of the
file that @code{hostname} should read from.

@itemize @bullet
@item
To run @code{hostname} and specify that the file @file{host.info} is the
file to read from, type:

@example
$ @kbd{hostname -F host.info @key{RET}}
@end example
@end itemize


@node Password, Users, Commands, Basics
@comment  node-name,  next,  previous,  up
@section Changing Your Password
@cindex changing your password
@cindex password, changing your
@pindex passwd

@noindent
To change your password, use the @code{passwd} tool. It prompts you for
your current password and a new password to replace it with. For
security purposes, neither the old nor the new password is echoed to the
screen as you type it. To make sure that you type the new password
correctly, @code{passwd} prompts you for your new password twice. You
must type it exactly the same way both times, or @code{passwd} will not
change your password.

@itemize @bullet
@item
To change your password, type:
@end itemize

@example
@cartouche
$ @kbd{passwd @key{RET}}
Changing password for kurt
Old password: @kbd{@var{your current password} @key{RET}}
Enter the new password (minimum of 5, maximum of 8 characters)
Please use a combination of upper and lower case letters and numbers.
New password: @kbd{@var{your new password} @key{RET}}
Re-enter new password: @kbd{@var{your new password} @key{RET}}
Password changed.
$
@end cartouche
@end example

@sp .25
@noindent
@strong{NOTE:} Passwords can contain uppercase and lowercase letters,
the digits 0 through 9, and punctuation marks; they should be between
five and eight characters long. @xref{Accounts, , Accounts and
Privileges}, for suggestions on choosing a good password.


@node Users, Processes, Password, Basics
@comment  node-name,  next,  previous,  up
@section Listing User Activity
@cindex listing user activity
@cindex user activity, listing

@noindent
The recipes in this section describe some of the simple commands for
finding out who you are currently sharing the system with and what they
are doing.

@menu
* Whoami::                      Finding out who you are.
* Who::                         Listing who is on the system.
* W::                           Listing who is on and what they're doing.
* Last::                        Listing when a user last logged on.
@end menu


@node Whoami, Who, Users, Users
@comment  node-name,  next,  previous,  up
@subsection Listing Your Username
@cindex listing your username
@cindex username, listing your
@pindex whoami

@noindent
Use @code{whoami} to output the username of the user that is logged in
at your terminal. This is not as inutile a command as one might first
think---if you're at a shared terminal, it's useful to determine whether
or not it is your account that you're messing in, and for those with
multiple accounts on a system, it's useful to see which of them you're
currently logged in with.

@itemize @bullet
@item
To output your username, type:

@example
@cartouche
$ @kbd{whoami @key{RET}}
kurt
$
@end cartouche
@end example
@end itemize

In this example, the username of the user logged in at this terminal is
@samp{kurt}.


@node Who, W, Whoami, Users
@comment  node-name,  next,  previous,  up
@subsection Listing Who Is on the System
@cindex listing who is on the system
@cindex system, listing who is on the
@cindex users, listing which are on
@pindex who

@noindent
Use @code{who} to output a list of all the users currently logged in to
the system. It outputs a minimum of three columns, listing the username,
terminal location, and time of login for all users on the system. A
fourth column is displayed if a user is using the X Window System; it
lists the window location of the user's session (@pxref{X, , The X
Window System}).

@itemize @bullet
@item
To see who is currently logged in, type:

@example
@cartouche
$ @kbd{who @key{RET}}
murky    tty1     Oct 20 20:09
dave     tty2     Oct 21 14:37
kurt     tty3     Oct 21 15:04
kurt     ttyp1    Oct 21 15:04 (:0.0)
$
@end cartouche
@end example
@end itemize

The output in this example shows that the user @code{murky} is logged in
on @code{tty1} (the first virtual console on the system), and has been
on since 20:09 on 20 October. The user @code{dave} is logged in on
@code{tty2} (the second virtual console), and has been on since 14:37 on
21 October. The user @code{kurt} is logged in twice---on @code{tty3}
(the third virtual console), and @code{ttyp1}, which is an X session
with a window location of @samp{(:0.0)}.

@sp .25
@noindent
@strong{NOTE:} This command is for listing the users on the local
system; to list the users connected to a different system on the
network, or to see more detailed information that a user may have made
public about himself, see @ref{Finger, , Checking Whether a User Is
Online}.


@node W, Last, Who, Users
@comment  node-name,  next,  previous,  up
@subsection Listing Who Is on and What They're Doing
@cindex listing who is on and what they're doing
@cindex users, listing what they are doing
@pindex w

@noindent
The @code{w} tool is similar to @code{who}, but it displays more
detail. It outputs a header line that contains information about the
current system status, including the current time, the amount of time
the system has been up and running, and the number of users on the
system. It then outputs a list of users currently logged in to the
system, giving eight columns of information for each. These columns
include username, terminal location, X session (if any), the time of
login, the amount of time the user has been idle, and what command the
user is running. (It also gives two columns showing the amount of time
the system's CPU has spent on all of the user's current jobs (``JCPU'')
and foreground process (``PCPU''); processes are discussed in
@ref{Processes, , Listing System Activity}, and jobs in @ref{Managing
Jobs, , Managing Jobs}.)

@itemize @bullet
@item
To see who is currently logged in and what they are doing, type:
@end itemize

@example
@cartouche
$ @kbd{w @key{RET}}
  5:27pm  up 17:53,  4 users,  load average: 0.12, 0.06, 0.01
USER     TTY      FROM       LOGIN@   IDLE   JCPU   PCPU  WHAT
murky    tty1          Oct 20 20:09 17:22m  0.32s  0.32s  -bash
dave     tty2                 14:37 13.00s  2:35   0.07s  less foo
kurt     tty3                 15:04  1:00m  0.41s  0.09s  startx
kurt     ttyp1    :0.0        15:04  0:00s 21.65s 20.96s  emacs
$
@end cartouche
@end example

In this example, the command's output shows that the current system time
is 5:27 p.m., the system has been up for 17 hours and 53 minutes, and
there are four users currently logged in: @code{murky} is logged in at
@code{tty1}, has been idle for 17 hours and 22 minutes, and is at a
@code{bash} shell prompt; @code{dave} is logged in at @code{tty2}, has
been idle for 13 seconds, and is using @code{less} to peruse a file
called @file{foo} (@pxref{Perusing Text, , Perusing Text}); and
@code{kurt} is logged in at two terminals---@code{tty3} and
@code{ttyp1}, which is an X session. He ran the @code{startx} command on
@code{tty3} to start his X session, and within his X session, he is
currently using Emacs.


@node Last, , W, Users
@comment  node-name,  next,  previous,  up
@subsection Listing the Last Times a User Logged In
@cindex listing the last times a user logged in
@cindex users, listing when they last logged in
@pindex last

@noindent
Use @code{last} to find out who has recently used the system, which
terminals they used, and when they logged in and out.

@itemize @bullet
@item
To output a list of recent system use, type:

@example
$ @kbd{last @key{RET}}
@end example
@end itemize

To find out when a particular user last logged in to the system, give
his username as an argument.

@itemize @bullet
@item
To find out when user @code{kurt} last logged in, type:

@example
$ @kbd{last kurt @key{RET}}
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} The @code{last} tool gets its data from the system file
@file{/var/log/wtmp}; the last line of output tells how far this file
goes back. Sometimes, the output will go back for several weeks or more.


@node Processes, Help, Users, Basics
@comment  node-name,  next,  previous,  up
@section Listing System Activity
@cindex listing system activity
@cindex system activity, listing
@cindex processes, listing
@cindex process ID
@cindex PID
@pindex ps

@noindent
When you run a command, you are starting a @dfn{process} on the system,
which is a program that is currently executing. Every process is given a
unique number, called its @dfn{process ID}, or ``PID.''

Use @code{ps} to list processes on the system. Some of the information
it can display about a process includes process ID, name of command
being run, username running the command, and how long the process has
been running. By default, @code{ps} outputs 5 columns: process ID, the
name of the terminal from which the process was started, the current
status of the process (including @samp{S} for @dfn{sleeping}, meaning
that it is on hold at the moment, @samp{R} meaning that it is running,
and @samp{Z} meaning that it is a @dfn{zombie} process, or a process
that has already died), the total amount of time the CPU has spent on
the process since the process started, and finally the name of the
command being run.

The following recipes describe popular usage of @code{ps}.

@menu
* Current Processes::           Listing your processes.
* User Processes::              Listing someone else's processes.
* All Processes::               Listing all of the processes on the system.
* Named Processes::             Listing processes by name or number.
@end menu


@node Current Processes, User Processes, Processes, Processes
@comment  node-name,  next,  previous,  up
@subsection Listing Your Current Processes
@cindex listing your current processes
@cindex processes, listing your current
@cindex sleeping process
@cindex zombie process

@noindent
Type @kbd{ps} with no arguments to list the processes you have running
in your current shell session. 

@itemize @bullet
@item
To list the processes in your current shell session, type:

@example
@cartouche
$ @kbd{ps @key{RET}}
  PID TTY STAT TIME COMMAND
  193   1 S    0:01 -bash 
  204   1 S    0:00 ps
$
@end cartouche
@end example
@end itemize

In this example, @code{ps} shows that two processes are running: the
@code{bash} and @code{ps} commands.  


@node User Processes, All Processes, Current Processes, Processes
@comment  node-name,  next,  previous,  up
@subsection Listing All of a User's Processes
@cindex listing all of a user's processes
@cindex processes, listing all of a user's

@noindent
To list all the processes of a specific user, use @code{ps} and give the
username to list as an argument to the @samp{-u} option. While you can't
snoop on the actual activities of other users, you can list the commands
they are running at a given moment.

@itemize @bullet
@item
To list all the processes that user @code{hst} has running on the
system, type: 

@example
$ @kbd{ps -u hst @key{RET}}
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} This command is useful for listing all of your own
processes, across all terminals and shell sessions; give your @emph{own}
username as an argument.


@node All Processes, Named Processes, User Processes, Processes
@comment  node-name,  next,  previous,  up
@subsection Listing All Processes on the System
@cindex listing all processes on the system
@cindex processes, listing all on the system
@pindex top
@pindex uptime
@pindex free

@noindent
To list all processes by all users on the system, use the @samp{aux}
options.

@itemize @bullet
@item
To list all of the processes and give their usernames, type:

@example
$ @kbd{ps aux @key{RET}}
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} There could be a lot of output---even single-user Linux
systems typically have fifty or more processes running at one time---so
you may want to pipe the output of this command through @code{less} for
perusal (@pxref{Perusing Text, , Perusing Text}).

Additionally, use @code{top} to show a display of all processes on the
system, sorted by their demand on the system resources. The display is
continually updated with current process information; press @kbd{Q} to
stop the display and exit the program. This tool also displays the
information about system runtime and memory that can be output with the
@code{uptime} and @code{free} commands.

@itemize @bullet
@item
To display a continually updated display of the current system
processes, type:

@example
$ @kbd{top @key{RET}}
@end example
@end itemize


@node Named Processes, , All Processes, Processes
@comment  node-name,  next,  previous,  up
@subsection Listing Processes by Name or Number
@cindex listing processes by name or number
@cindex processes, listing by name or number
@pindex grep

@noindent
To list processes whose output contains a name or other text to match,
list all processes and pipe the output to @code{grep}. This is useful
for when you want to see which users are running a particular program or
command.

@itemize @bullet
@item
To list all the processes whose commands contain reference to an
@file{sbin} directory in them, type:

@example
$ @kbd{ps aux | grep sbin @key{RET}}
@end example

@item
To list any processes whose process IDs contain a 13 in them, type:

@example
$ @kbd{ps aux | grep 13 @key{RET}}
@end example
@end itemize

To list the process (if any) which corresponds to a process ID, give
that PID as an argument to the @samp{-p} option.

@itemize @bullet
@item
To list the process whose PID is 344, type:

@example
$ @kbd{ps -p 344 @key{RET}}
@end example
@end itemize


@node Help, , Processes, Basics
@comment  node-name,  next,  previous,  up
@section Help Facilities
@cindex help facilities

@noindent
Linux systems come with a lot of help facilities, including complete
manuals in etext form. In fact, the foremost trouble with Linux
documentation isn't that there is not enough of it, but that you have to
sift through the mounds of it, trying to find the precise information
you're looking for!

I describe the help facilities in the following sections; their relative
usefulness for the particular kind of information you're looking for is
noted.

If you find that you need more help, don't panic---other options are
available. They're described in @ref{Getting Help, , If You Need More
Help}.

@menu
* Apropos::                     Finding the right tool to use.
* Whatis::                      Getting a description of a tool.
* Usage Help::                  Getting usage help for a tool.
* Man::                         The online manuals.
* Info::                        The GNU hypertext Info system.
* HOWTOs::                      Other documentation on the system.
@end menu


@node Apropos, Whatis, Help, Help
@comment  node-name,  next,  previous,  up
@subsection Finding the Right Tool for the Job
@cindex finding the right tool for the job
@cindex tool, finding the right one
@cindex software, listing those that match a keyword.
@cindex manual pages, searching
@pindex apropos
@pindex dpkg
@pindex man

@noindent
When you know what a particular tool or application @emph{does}, but you
can't remember it's name, use @code{apropos}. This tool takes a keyword
as an argument, and it outputs a list of installed software whose
one-line descriptions contain that keyword. This is also useful for
finding software on your system related to, say, ``audio'' or ``sound''
or ``sort'' or some other such general concept.

@itemize @bullet
@item
To output a list of programs that pertain to consoles, type:

@example
@cartouche
$ @kbd{apropos consoles @key{RET}}
console (4)          - console terminal and virtual consoles
gpm (1)              - a cut and paste utility and mouse server for
                       virtual consoles
$
@end cartouche
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} The @code{apropos} tool only finds exact matches, so a
search for the keyword @samp{console} might not list the programs that a
search for the keyword @samp{consoles} would yield, and vice versa.

Another way to find tools by keyword is to search the system manual
pages (@pxref{Man, , Reading a Page from the System Manual}). To do
this, use @code{man} and give the text to search for as an argument to
the @samp{-k} option. This searches the short descriptions and manual
page names for the given text, and outputs a list of those tools that
match in the same format as the @code{apropos} tool.

@itemize @bullet
@item
To output a list of all tools whose pages in the system manual contain a
reference to consoles, type:

@example
$ @kbd{man -k consoles @key{RET}}
@end example
@end itemize

On Debian systems, yet another way to find installed software by keyword
is to use @code{dpkg}, the Debian package tool. Use the @samp{-l} option
to list all of the installed packages, which are each output on a line
of their own with their package name and a brief description.

You can output a list of packages that match a keyword by piping the
output to @code{grep}. Use the @samp{-i} option with @code{grep} to
match keywords regardless of case (@code{grep} is discussed in
@ref{Searching Text, , Searching Text}).

Additionally, you can directly peruse the file
@file{/var/lib/dpkg/available}; it lists all available packages and
gives a description of them.

@itemize @bullet
@item
To list all of the packages on the system, type:

@example
$ @kbd{dpkg -l @key{RET}}
@end example

@item
To list all of the packages whose name or description contains the text
``edit,'' regardless of case, type:

@example
$ @kbd{dpkg -l | grep -i edit @key{RET}}
@end example

@item
To peruse descriptions of the packages that are available, type:

@example
$ @kbd{less /var/lib/dpkg/available @key{RET}}
@end example
@end itemize


@node Whatis, Usage Help, Apropos, Help
@comment  node-name,  next,  previous,  up
@subsection Listing a Description of a Program
@cindex listing a description of a program
@cindex program, listing a description of a 
@pindex whatis

@noindent
Use @code{whatis} to list a one-line description of a program. Give the
name of the tool or application to list as an argument.

@itemize @bullet
@item
To get a description of the @code{who} tool, type:

@example
$ @kbd{whatis who @key{RET}}
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} The @code{whatis} tool gets its descriptions from the
@emph{manual page} of a given program; manual pages are described later
in this section, in @ref{Man, , Reading a Page from the System Manual}.


@node Usage Help, Man, Whatis, Help
@comment  node-name,  next,  previous,  up
@subsection Listing the Usage of a Tool
@cindex listing the usage of a tool
@cindex tool, listing the usage of a
@cindex commands, listing usage
@pindex whoami

@noindent
Many tools have a long-style option, @samp{--help}, that outputs usage
information about the tool, including the options and arguments the tool
takes.

@itemize @bullet
@item
To list the possible options for @code{whoami}, type:

@example
@cartouche
$ @kbd{whoami --help @key{RET}}
Usage: whoami [OPTION]...
Print the user name associated with the current effective user id.
Same as id -un.

  --help      display this help and exit
  --version   output version information and exit

Report bugs to sh-utils-bugs@@gnu.ai.mit.edu
$
@end cartouche
@end example
@end itemize

This command outputs some usage information about the @code{whoami}
tool, including a short description and a list of possible options.

@sp .25
@noindent
@strong{NOTE:} Not all tools take the @samp{--help} option; some tools
take a @samp{-h} or @samp{-?} option instead, which performs the same
function.


@node Man, Info, Usage Help, Help
@comment  node-name,  next,  previous,  up
@subsection Reading a Page from the System Manual
@cindex reading a page from the system manual
@cindex system manual, reading a page from the
@cindex manual pages, reading
@pindex man

@noindent
In the olden days, the hardcopy reference manual that came with most
Unix systems also existed electronically on the system itself; each
software program that came with the system had its own @dfn{manual page}
(often called a ``man page'') that described it. This is still true on
Linux-based systems today, except they don't always come with a hardcopy
manual.

Use the @code{man} tool to view a page in the system manual. As an
argument to @code{man}, give the name of the program whose manual page
you want to view (so to view the manual page for @code{man}, you would
type @kbd{man man}).

@itemize @bullet
@item
To view the manual page for @code{w}, type:

@example
$ @kbd{man w @key{RET}}
@end example
@end itemize

This command displays the manual page for @code{w}:

@cartouche
@image{basic-commands-man-01, 5 in}
@end cartouche

Use the up and down arrow keys to move through the text. Press @key{Q}
to stop viewing the manual page and exit @code{man}. Since @code{man}
uses @code{less} to display the text, you can use any of the @code{less}
keyboard commands to peruse the manual page (@pxref{Perusing Text, ,
Perusing Text}).

Despite its name, a manual page does not always contain the complete
documentation to a program, but it's more like a quick reference. It
usually gives a short description of the program, and lists the options
and arguments it takes; some manual pages also include an example or a
list of related commands. (Sometimes, commands have very complete,
extensive manual pages, but more often, their complete documentation is
found either in other help files that come with it or in its Info
documentation; these are subjects of the following two recipes.) 

To prepare a @code{man} page for printing, see @ref{Preparing Man, ,
Preparing a Man Page for Printing}.


@node Info, HOWTOs, Man, Help
@comment  node-name,  next,  previous,  up
@subsection Using the GNU Info System
@cindex using the GNU Info system
@cindex GNU Info System, using the
@cindex Free Software Foundation
@pindex info

@noindent
The GNU Info System is an online hypertext reference system for
documentation prepared in the Info format. This documentation tends to
be more complete than a typical @code{man} page, and often, the Info
documentation for a given software package will be an entire book or
manual. All of the manuals published by the Free Software Foundation are
released in Info format; these manuals contain the same text
(@emph{sans} illustrations) as the paper manuals that you can purchase
directly from the Free Software Foundation.

There are different ways to peruse the Info documentation: you can use
the standalone @code{info} tool, read Info files in the Emacs editor
(@pxref{Emacs, , Emacs}), or use one of the other tools designed for
this purpose. Additionally, tools exist for converting Info
documentation to HTML that you can read in a Web browser
(@pxref{Browsing Files, , Browsing Files}). 

To read the Info manual for a tool or application with the @code{info}
tool, give its name as an argument. With no arguments, @code{info} opens
your system's @code{Top} Info menu, which lists all of the available
manuals that are installed on the system.

@itemize @bullet
@item
To view all of the Info manuals on the system, type:

@example
$ @kbd{info @key{RET}}
@end example
@end itemize

This command starts @code{info} at the system's @code{Top} menu, which
shows some of the @code{info} key commands and displays a list of
available manuals: 

@cartouche
@image{basic-commands-info-01, 5 in}
@end cartouche

Use the arrow keys to move through each ``page'' of information, called
an Info @dfn{node}. Nodes are the base unit of information in Info, and
are arranged hierarchically---a manual's @code{Top} node will contain an
Info @dfn{menu} containing links to its various chapters, and a chapter
node will contain a menu with links for its sections, and so on. Links
also appear as cross references in the text.

Links look the same in both menu items and cross references: an asterisk
(@samp{*}), the name of the node it links to, and either one or two
colon characters (@samp{:}). To follow a link to the node it points to,
move the cursor over any part of the node name in the link and press
@key{RET}.

To run a tutorial that describes how to use @code{info}, press the
@key{H} key. Press @key{Q} at any time to stop reading the documentation
and exit @code{info}.

To read Info documentation for a tool or application, give its name as
an argument to @code{info}; if no Info manual exists for that tool,
@code{info} displays the @code{man} page for that tool instead.

@itemize @bullet
@item
To read the Info documentation for the @code{tar} tool, type:

@example
$ @kbd{info tar @key{RET}}
@end example
@end itemize

This command opens a copy of @cite{The GNU tar Manual} in @code{info}. 

To read the contents of a file written in Info format, give the name of
the file to read with the @samp{-f} option. This is useful for reading
an Info file that you have obtained elsewhere, and is not in the
@file{/usr/info} directory with the rest of the installed Info
files. Info can automatically recognize and expand Info files that are
compressed and have a @file{.gz} file name extension (@pxref{File
Compression, , Compressed Files}).

@itemize @bullet
@item
To read @file{faq.info}, an Info file in the current directory, type:

@example
$ @kbd{info -f faq.info @key{RET}}
@end example
@end itemize

This command starts @code{info} and opens the Info file @file{faq.info},
beginning at the top node in the file.

To read a specific @emph{node} in an Info file, give the name of the
node to use in quotes as an argument to the @samp{-n} option.  

@itemize @bullet
@item
To read @file{faq.info}, an Info file in the current directory,
beginning with the node @code{Text}, type:

@example
$ @kbd{info -n 'Text' -f faq.info @key{RET}}
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} You can also read Info documentation directly from the
Emacs editor; you type @kbd{C-h i} from Emacs to start the Info reader,
and then use the same commands as in the standalone @code{info} tool
(@pxref{Emacs Intro, , Getting Acquainted with Emacs}).

The Emacs ``incremental'' search command, @kbd{C-s}, also works in
@code{info}; it's a very fast, efficient way to search for a word or
phrase in an entire Info text (like this entire book); see @ref{Emacs
Incremental Search, , Searching Incrementally in Emacs}.


@node HOWTOs, , Info, Help
@comment  node-name,  next,  previous,  up
@subsection Reading System Documentation and Help Files
@cindex reading system documentation and help files
@cindex help files, reading
@cindex documentation, system
@cindex help files
@cindex FAQs
@cindex HOWTOs

@flushleft
@sf{Debian}: @file{doc-linux-text}
@sf{WWW}: @url{http://linuxdoc.org/}
@end flushleft
@*
@noindent
The @file{/usr/doc} directory is for miscellaneous documentation:
HOWTOs, FAQs, Debian-specific documentation files and documentation
files that come with commands. (To learn more about files and
directories, see @ref{Files and Directories, , Files and Directories}.)
To peruse any of these files, use @code{less}, described in full in
@ref{Perusing Text, , Perusing Text}.

When a software package is installed, any additional documentation files
it might have beyond a manual page and Info manual are placed here, in a
subdirectory with the name of that package. For example, additional
documentation for the @code{hostname} package is in
@file{/usr/doc/hostname}, and documentation for the @code{passwd}
package is in @file{/usr/doc/passwd}. Most packages have a file called
@file{README}, which usually contains relevant information. Often this
file is compressed as @file{README.gz}, in which case you can use
@code{zless} instead of @code{less}.

The Linux Documentation Project (LDP) has overseen the creation of
more than 100 ``HOWTO'' files, each of which covers a particular aspect
of the installation or use of Linux-based systems.

The LDP HOWTOs are compressed text files stored in the
@file{/usr/doc/HOWTO} directory; to view them, use @code{zless}. The
file @file{/usr/doc/HOWTO/HOWTO-Index.gz} contains an annotated index of
all the HOWTO documents installed on the system.@footnote{LDP documents
are available in other formats as well, including HTML and DVI.}

Finally, the @file{/usr/doc/FAQ} directory contains a number of FAQ
(``Frequently Asked Questions'') files on various subjects, and the
files that make up the Debian FAQ are in the @file{/usr/doc/debian/FAQ}
directory. The Debian FAQ is available both in HTML format, which you
can view in a Web browser (@pxref{Browsing Files, , Browsing Files}),
and as a compressed text file, which you can view in @code{zless}.

@itemize @bullet
@item
To view the HTML version of the Debian FAQ in the @code{lynx} Web
browser, type: 

@example
$ @kbd{lynx /usr/doc/debian/FAQ/debian-faq.html @key{RET}}
@end example

@item
To view the compressed text version of the Debian FAQ in @code{zless},
type:

@example
$ @kbd{zless /usr/doc/debian/FAQ/debian-faq.txt.gz @key{RET}}
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} It's often very useful to use a Web browser to browse
through the documentation files in these directories---see @ref{Browsing
Files, , Browsing Files}.

On some systems, @file{/usr/doc} is superseded by the
@file{/usr/share/doc} directory.