Chapter 1. Introduction

It is hard to chart the rise of Linux over its twelve years of existence without risking the appearance of exaggeration and hyperbole. During the past five years alone, Linux has grown from a student/hacker playground to an upstart challenger in the server market to a well-respected system taking its rightful place in educational and corporate networks. Many serious analysts claim that its trajectory has just begun, and that it will eventually become the world's most widespread operating system.

Linux was first developed by Linus Torvalds at the University of Helsinki in Finland. From his current location in Silicon Valley, Linus continues to centrally coordinate improvements. The Linux kernel continues to develop under the dedicated cultivation of a host of other programmers and hackers all over the world, joined by members of programming teams at major computer companies, all connected through the Internet.

By "kernel," we mean the core of the operating system itself, not the applications (such as the compiler, shells, and so forth) that run on it. Today, the term "Linux" is often used to mean a software environment with a Linux kernel along with a large set of applications and other software components. In this larger meaning, many people prefer the term GNU/Linux, which acknowledges the central role played by tools from the Free Software Foundation's GNU project in the development of the kernel.

Linux systems cannot be technically referred to as a "version of Unix," as they have not undergone the required tests and licensing.[1] However, Linux offers all the common programming interfaces of standard Unix systems, and as you can see from this book, all the common Unix utilities have been reimplemented on Linux. It is a powerful, robust, fully usable system for those who like Unix.

[1] Before an operating system can be called "Unix," it must be branded by The Open Group.

The historical impact of Linux goes beyond its role as a challenge to all versions of Unix as well as Microsoft Windows, particularly on servers. Linux's success has also inspired countless other free software or open source (defined at http://opensource.org) projects, including Samba, GNOME, and a mind-boggling collection of innovative projects that you can browse at numerous sites like SourceForge (http://sourceforge.net). As both a platform for other developers and a development model, Linux gave a tremendous boost to the GNU project, and has also become a popular platform for Java development. In short, Linux is a central participant in the most exciting and productive free software movement ever seen.

If you haven't obtained Linux yet, or have it but don't know exactly how to get started using it, see Other Resources in the preface.
    Team LiB


1.1 The Excitement of Linux

Linux is, first of all, free software: anyone can download the source from the Internet or buy it on a low-cost CD-ROM. But Linux is becoming well known because it's more than free software—it's unusually good software. You can get more from your hardware with Linux and be assured of fewer crashes; even its security is better than many commercial alternatives.

Linux first appeared in organizations as ad hoc installations by hackers running modest web servers or development systems at universities and research institutions, but now extends deeply into corporations around the world. People deploying Linux for mission-critical systems tend to talk about its ample practical advantages, such as the ability to deliver a lot of bang for the buck and the ease of deploying other powerful tools on Linux such as Apache, Samba, and Java environments. They also cite Linux's ability to grow and sprout new features of interest to large numbers of users. But these advantages can be traced back to the concept of software freedom, which is the root of the broad wave of innovation driving Linux.

As free software, Linux revives the grand creativity and the community of sharing that Unix was long known for. The unprecedented flexibility and openness of Unix—which newcomers usually found confusing and frustrating, but eventually found they couldn't live without—continually inspired extensions, new tools like Perl, and experiments in computer science that sometimes ended up in mainstream commercial computer systems.

Many programmers fondly remember the days when AT&T provided universities with Unix source code at no charge, and the University of Berkeley started distributing its version in any manner that allowed people to get it. For these older hackers, Linux brings back the spirit of working together—all the more so because the Internet is now so widespread. And for the many who are too young to remember the first round of open systems or whose prior experience has been constricted by trying to explore and adapt proprietary operating systems, now is the time to discover the wonders of freely distributable source code and infinitely adaptable interfaces.

The economic power behind Linux's popularity is its support for an enormous range of hardware. People who are accustomed to MS-DOS and Microsoft Windows are often amazed at how much faster their hardware appears to work with Linux—it makes efficient use of its resources.

For the first several years, users were attracted to Linux for a variety of financial and political reasons, but soon they discovered an unexpected benefit: Linux works better than many commercial systems. With the Samba file and print server, for instance, Linux serves a large number of end-user PCs without crashing. With the Apache web server, it provides more of the useful features web administrators want than competing products do. Embedded versions of the Linux kernel are in growing use because, although they are larger than the most stripped-down operating systems, they deliver a range of powerful features within a remarkably small footprint.

Opinions still differ on how suitable Linux is as a general-purpose desktop system. But the tremendous advances in usability and stability of the desktop software and its applications are undisputed. Soon (if not today), one will find Linux in many offices and other end-user environments. Meanwhile, the strides made by Linux in everyday computing tasks are reflected in the new audio and CD-related commands found in this edition.


1.2 Distribution and Support

While it is convenient to download one or two new programs over the Internet and fairly feasible to download something as large as the Linux kernel, getting an entire working system over the Internet is difficult without a high-speed Internet connection. Over the years, therefore, commercial and noncommercial packages called distributions have emerged. The first distribution consisted of approximately 50 diskettes, at least one of which would usually turn out to be bad and have to be replaced. When CD-ROM drives became widespread, Linux really took off.

After getting Linux, the average user is concerned next with support. While Usenet newsgroups offer very quick responses and meet the needs of many intrepid users, you can also buy support from the vendors of the major distributions and a number of independent experts. Linux is supported at least as well as commercial software. When you buy a distribution from a vendor, you typically are entitled to a period of free support as well.

Intel's x86 family and other compatible chips are still by far the most common hardware running Linux, but Linux is also now commercially available on a number of other hardware systems, notably the PowerPC, the 64-bit Intel Itanium processor, Sun Microsystems' SPARC, and the Alpha (created by Digital Equipment Corporation).


1.3 Commands on Linux

Linux commands are not the same as standard Unix ones. They're better! This is because most of them are provided by the GNU project run by the Free Software Foundation (FSF). GNU means "GNU's Not Unix"—the first word of the phrase is expanded with infinite recursion.

Benefiting from years of experience with standard Unix utilities and advances in computer science, programmers on the GNU project have managed to create versions of standard tools that have more features, run faster and more efficiently, and lack the bugs and inconsistencies that persist in the original standard versions.

While GNU provided the programming utilities and standard commands like grep, many of the system and network administration tools on Linux came from the Berkeley Software Distribution (BSD). In addition, some people wrote tools that specifically allow Linux to deal with special issues such as filesystems. This book documents all the standard Unix commands that are commonly available on most Linux distributions.

The third type of software most commonly run on Linux is the X Window System, ported by the XFree86 project to standard Intel chips. While this book cannot cover the wide range of utilities that run on X, we briefly cover some of the useful customizations you can make to your KDE, GNOME, or fvwm2 desktop.


1.4 What This Book Offers

Originally based on the classic O'Reilly & Associates quick reference, Unix in a Nutshell, this book has been expanded to include much information that is specific to Linux. These enhancements include chapters on:

  • Package managers (which make it easy to install, update, and remove related software files)

  • The KDE and GNOME desktops and the fvwm2 window manager

  • Boot parameters

  • The CVS version control system

The book also contains dozens of Linux-specific commands, along with tried-and-true Unix commands that have been supporting users for decades (though they continue to sprout new options).

This book does not cover the graphical tools contained in most distributions of Linux. Many of these, to be sure, are quite useful and can form the basis of everyday work. Examples of these tools include OpenOffice (the open source version of the StarOffice suite distributed by Sun Microsystems), Evolution (a mail, calendar, and office productivity tool from Ximian), Mozilla (the open source cousin of the Netscape web browser), and the GIMP (a graphic image manipulation program and the inspiration for the GNOME project). But they are not Linux-specific, and their graphical models do not fit well into the format of this book.

While you can do a lot of valuable work with the graphical applications, the core of Linux use is the text manipulation and administration done from the command line, within scripts, or using text editors such as vi and Emacs. Linux is still mostly a command-driven system, and this book continues to focus on this level of usage. In your day-to-day work, you'll likely find yourself moving back and forth between graphical programs and the commands listed in this book.

Every distribution of Linux is slightly different, but you'll find that the commands we document are the ones you use most of the time, and that they work the same on all distributions. Basic commands, programming utilities, system administration, and network administration are all covered. However, some areas were so big that we had to leave them out. The many applications that depend on the X Window System didn't make the cut. Nor did the many useful programming languages like Java, Perl, and Python with which users can vastly expand the capabilities of their systems. XML isn't covered here either. These subjects would stretch the book out of its binding.

Linux in a Nutshell doesn't teach you Linux—it is, after all, a quick reference—but novices as well as highly experienced users will find it of great value. When you have some idea of what command you want but aren't sure just how it works or what combinations of options give you the exact output required, this book is the place to turn. It can also be an eye-opener, making you aware of options that you never knew about before.

Once you're over the hurdle of installing Linux, the first thing you need to do is get to know the common utilities run from the shell prompt. If you know absolutely nothing about Unix, we recommend you read a basic guide (introductory chapters in the O'Reilly books Learning Red Hat Linux and Running Linux can get you started.) This chapter and Chapter 2 offer a context for understanding different kinds of commands (including commands for programming, system administration, and network administration). Chapter 3 is the central focus of the book, containing about one half its bulk.

The small chapters immediately following Chapter 3 help you get your system set up. Since most users do not want to completely abandon other operating systems (whether a Microsoft Windows system, OS/2, or some Unix flavor), Linux often resides on the same computer as other systems. Users can then boot the system they need for a particular job. Chapter 5 describes the commonly used booting options on Intel systems, including LILO (Linux Loader), GRUB (the GRand Unified Bootloader), and Loadlin. Chapter 5 covers the Red Hat package manager (rpm)—which is supported by many distributions, including Red Hat, SuSE, Mandrake, and Caldera—and the Debian package manager. Package managers are useful for installing and updating software; they make sure you have all the files you need in the proper versions.

All commands are interpreted by the shell. The shell is simply a program that accepts commands from the user and executes them. Different shells sometimes use slightly different syntax to mean the same thing. Under Linux, two popular shells are bash and tcsh (which on Linux has supplanted the older csh), and they differ in subtle ways. (One of the nice things about Linux and other Unix systems is that you have a variety of shells to choose from, each with strengths and weaknesses.) We offer an introduction to shells in Chapter 6, thorough coverage of bash in Chapter 7, and a guide to tcsh in Chapter 8. You may decide to read these after you've used Linux for a while, because they mostly cover powerful, advanced features that you'll want when you're a steady user.

To get any real work done, you'll have to learn some big, comprehensive utilities, notably an editor and some scripting tools. Two major editors are used on Linux: vi and Emacs. Emacs is covered in Chapter 10 and vi in Chapter 11. Chapter 12 and Chapter 13 cover two classic Unix tools for manipulating text files on a line-by-line basis: sed and gawk (the GNU version of the traditional awk). O'Reilly offers separate books about these topics that you may find valuable, as they are not completely intuitive upon first use. (Emacs does have an excellent built-in tutorial, though; to invoke it, press Ctrl-H followed by t for "tutorial.")

CVS (Concurrent Versions System) and RCS (Revision Control System) manage files so you can retrieve old versions and maintain different versions simultaneously. Originally used by programmers who have complicated requirements for building and maintaining applications, these tools have turned out to be valuable for anyone who maintains files of any type, particularly when coordinating a team of people. CVS has become a distribution channel for thousands of free software projects. Chapter 14 presents RCS commands, and Chapter 15 presents CVS commands.

Graphical desktops are covered in four chapters. Chapter 16 is a brief overview to the major options on Linux systems. It is followed by Chapter 17 on the GNOME desktop, Chapter 18 on the KDE desktop, and Chapter 19 on the fvwm2 window manager.

Our goal in producing this book is to provide convenience, and that means keeping the book (relatively) small. It certainly doesn't have everything the manual pages have; but you'll find that it has what you need 95% of the time.


1.5 Sources and Licenses

Some distributions contain the source code for Linux; it is also easily available for download at http://www.kernel.org and elsewhere. Source code is similarly available for all the utilities on Linux (unless your vendor offers a commercial application or library as a special enhancement). You may never bother looking at the source code, but it's key to Linux's strength. Under the Linux license, the source code has to be provided by the vendor, and it permits those who are competent at such things to fix bugs, provide advice about the system's functioning, and submit improvements that benefit everyone. The license is the GNU project's well-known General Public License, also known as the GPL or "copyleft," invented and popularized by the Free Software Foundation.

The FSF, founded by Richard Stallman, is a phenomenon that many people might believe to be impossible if it did not exist. (The same goes for Linux, in fact—15 years ago, who would have imagined a robust operating system developed by collaborators over the Internet and made freely redistributable?) One of the most popular editors on Unix, GNU Emacs, comes from the FSF. So do gcc and g++ (C and C++ compilers), which for a while set the standard in the industry for optimization and fast code. One of the largest projects within GNU is the GNOME desktop, which encompasses several useful general-purpose libraries and applications that use these libraries to provide consistent behavior and interoperability.

Dedicated to the sharing of software, the FSF provides all its code and documentation on the Internet and allows anyone with a whim for enhancements to alter the source code. One of its projects is the Debian distribution of Linux.

To prevent hoarding, the FSF requires that the source code for all enhancements be distributed under the same GPL that it uses. This encourages individuals or companies to make improvements and share them with others. The only thing someone cannot do is add enhancements and then try to sell the product as commercial software—that is, to withhold the source code. That would be taking advantage of the FSF and the users. You can find the GPL in any software covered by that license, or online at http://www.gnu.org/copyleft/gpl.html.

As we said earlier, many Linux tools come from BSD instead of GNU. BSD is also free software. The license is significantly different, but that probably don't concern you as a user. The effect of the difference is that companies are permitted to incorporate the software into their proprietary products, a practice that is severely limited by the GNU license.


1.6 Beginner's Guide

If you're just beginning to work on a Linux system, the abundance of commands might prove daunting. To help orient you, the following lists present a sampling of commands on various topics.

1.6.1 Communication

ftp | File Transfer Protocol.
login | Sign on.
rlogin | Sign on to remote system.
rsh | Run shell or single command on remote system (not particularly secure).
ssh | Run shell or single command on remote system (secure).
talk | Exchange messages interactively with other terminals.
telnet | Connect to another system.
tftp | Trivial File Transfer Protocol.
uudecode | Decode file prepared for mailing by uuencode.
uuencode | Encode file containing binary characters for mailing.
vacation | Respond to mail automatically.

1.6.2 Comparisons

cmp | Compare two files, byte by byte.
comm | Compare items in two sorted files.
diff | Compare two files, line by line.
diff3 | Compare three files.

1.6.3 File Management

cat | Concatenate files or display them.
chfn | Change user information for finger, email, etc.
cksum | Compute checksum.
chmod | Change access modes on files.
chsh | Change login shell.
cp | Copy files.
csplit | Split a file into pieces with a specific size or at specific locations.
dd | Copy files in raw disk form.
file | Determine a file's type.
head | Show the first few lines of a file.
less | Display files by screenful.
ln | Create filename aliases.
ls | List files or directories.
merge | Merge changes from different files.
mkdir | Create a directory.
more | Display files by screenful.
mv | Move or rename files or directories.
newgrp | Change current group.
pwd | Print working directory.
rcp | Copy files to remote system.
rm | Remove files.
rmdir | Remove directories.
split | Split files evenly.
tail | Show the last few lines of a file.
wc | Count lines, words, and characters.

1.6.4 Media

cdda2wav | Rip a CD to create a computer-friendly WAV format.
cdparanoia | Rip a CD while providing extra features.
cdrdao | Copy a CD.
cdrecord | Record to a CD.
eject | Eject a removable disk or tape.
mpg321 | Play an MP3 file.
volname | Provide the volume name of a CD-ROM.

1.6.5 Printing

lpq | Show status of print jobs.
lpr | Send to the printer.
lprm | Remove print job.
lpstat | Get printer status.
pr | Format and paginate for printing.

1.6.6 Programming

ar | Create and update library files.
as | Generate object file.
bison | Generate parsing tables.
cpp | Preprocess C code.
flex | Lexical analyzer.
g++ | GNU C++ compiler.
gcc | GNU C compiler.
ld | Link editor.
m4 | Macro processor.
make | Create programs.
ranlib | Regenerate archive symbol table.
rpcgen | Translate RPC to C code.
yacc | Generate parsing tables.

1.6.7 Program Maintenance

cvs | Manage different versions (revisions) of source files.
etags | Generate symbol list for use with the Emacs editor.
gdb | GNU debugger.
gprof | Display object file's profile data.
imake | Generate makefiles for use with make.
make | Maintain, update, and regenerate related programs and files.
nm | Display object file's symbol table.
patch | Apply patches to source code.
rcs | Manage different versions (revisions) of source files.
size | Print the size of an object file in bytes.
strace | Trace system calls and signals.
strip | Strip symbols from an object file.

1.6.8 Searching

apropos | Search manpages for topic.
egrep | Extended version of grep.
fgrep | Search files for literal words.
find | Search the system for files by name and take a range of possible actions.
grep | Search files for text patterns.
locate | Search a preexisting database to show where files are on the system.
strings | Search binary files for text patterns.
whereis | Find command.

1.6.9 Shell Programming

echo | Repeat command-line arguments on the output.
expr | Perform arithmetic and comparisons.
printf | Format and print command-line arguments.
sleep | Pause during processing.
test | Test a condition.

1.6.10 Storage

bzip2 | Compress files to free up space.
cpio | Create and unpack file archives.
gunzip | Expand compressed (.gz and .Z) files.
gzip | Compress files to free up space.
shar | Create shell archive.
tar | Copy files to or restore files from an archive medium.
zcat | Display contents of compressed files.

1.6.11 System Status

at | Execute commands later.
atq | Show jobs queued by at.
atrm | Remove job queued by at.
chgrp | Change file group.
chown | Change file owner.
crontab | Automate commands.
date | Display or set date.
df | Show free disk space.
du | Show disk usage.
env | Show environment variables.
finger | Display information about users.
kill | Terminate a running command.
printenv | Show environment variables.
ps | Show processes.
stty | Set or display terminal settings.
who | Show who is logged in.

1.6.12 Text Processing

col | Process control characters.
cut | Select columns for display.
emacs | Work environment with powerful text editing capabilities.
ex | Line editor underlying vi.
expand | Convert tabs to spaces.
fmt | Produce roughly uniform line lengths.
fold | Break lines.
gawk | Process lines or records one by one.
ghostscript | Display PostScript or PDF file.
groff | Format troff input.
ispell | Interactively check spelling.
join | Merge different columns into a database.
paste | Merge columns or switch order.
rev | Print lines in reverse.
sed | Noninteractive text editor.
sort | Sort or merge files.
tac | Print lines in reverse.
tr | Translate (redefine) characters.
uniq | Find repeated or unique lines in a file.
vi | Visual text editor.
xargs | Process many arguments in manageable portions.

1.6.13 Miscellaneous

banner | Make posters from words.
bc | Arbitrary precision calculator.
cal | Display calendar.
clear | Clear the screen.
man | Get information on a command.
nice | Reduce a job's priority.
nohup | Preserve a running job after logging out.
passwd | Set your login password.
script | Produce a transcript of your login session.
su | Become a superuser.
tee | Simultaneously store output in file and send to screen.
which | Print pathname of a command.


2.1 Common Commands

Following are lists of commonly used system administration commands.

2.1.1 Clocks

hwclock | Manage hardware clock.
rdate | Get time from network time server.
zdump | Print list of time zones.
zic | Create time conversion information files.

2.1.2 Daemons

apmd | Advanced Power Management daemon.
atd | Queue commands for later execution.
bootpd | Internet Boot Protocol daemon.
fingerd | Finger daemon.
ftpd | File Transfer Protocol daemon.
identd | Identify user running TCP/IP process.
imapd | IMAP mailbox server daemon.
inetd | Internet services daemon.
klogd | Manage syslogd.
lpd | Printer daemon.
mountd | NFS mount request server.
named | Internet domain name server.
nfsd | NFS daemon.
pppd | Maintain Point-to-Point Protocol (PPP) network connections.
rdistd | Remote file distribution server.
rexecd | Remote execution server.
rlogind | rlogin server.
routed | Routing daemon.
rpc.rusersd | Remote users server.
rpc.statd | NFS status daemon.
rshd | Remote shell server.
rwhod | Remote who server.
sshd | Secure shell daemon.
syslogd | System logging daemon.
talkd | Talk daemon.
tcpd | TCP network daemon.
tftpd | Trivial File Transfer Protocol daemon.
update | Buffer flush daemon.
ypbind | NIS binder process.
yppasswdd | NIS password modification server.
ypserv | NIS server process.

2.1.3 Hardware

agetty | Start user session at terminal.
arp | Manage the ARP cache.
cardctl | Control PCMCIA cards.
cardmgr | PCMCIA card manager daemon.
cfdisk | Maintain disk partitions (graphical interface).
fdisk | Maintain disk partitions.
hdparm | Get and set hard drive parameters.
kbdrate | Manage the keyboard's repeat rate.
ramsize | Print information about RAM disk.
setkeycodes | Change keyboard scancode-to-keycode mappings.
setserial | Set serial port information.
slattach | Attach serial lines as network interfaces.

2.1.4 Host Information

arch | Print machine architecture.
dig | Query Internet domain name servers. Replaces nslookup.
dnsdomainname | Print DNS domain name.
domainname | Print NIS domain name.
free | Print memory usage.
host | Print host and zone information.
hostname | Print or set hostname.
nslookup | Query Internet domain name servers. (Deprecated)
uname | Print host information.

2.1.5 Installation

cpio | Copy file archives.
install | Copy files into locations providing user access and set permissions.
rdist | Distribute files to remote systems.
tar | Copy files to or restore files from an archive medium.

2.1.6 Mail

fetchmail | Retrieve mail from remote servers.
formail | Convert input to mail format.
mailq | Print a summary of the mail queue.
makemap | Update sendmail's database maps.
rmail | Handle uucp mail.
sendmail | Send and receive mail.

2.1.7 Managing Filesystems

To Unix systems, a filesystem is a device (such as a partition) that is formatted to store files. Filesystems can be found on hard drives, floppies, CD-ROMs, or other storage media that permit random access.

The exact format and means by which the files are stored are not important; the system provides a common interface for all filesystem types that it recognizes. Under Linux, filesystem types include the Second Extended (ext2) Filesystem, which you probably use to store Linux files. This filesystem was developed primarily for Linux and supports 256-character filenames and 4-terabyte maximum filesystem size. (It is "second" because it is the successor to the extended filesystem type.) Other common filesystem types include the MS-DOS filesystem, which allows files on MS-DOS partitions and floppies to be accessed under Linux, and the ISO 9660 filesystem used by CD-ROMs.

The 2.4 kernel adds optional support for an enhanced version of the ext2 filesystem, the Third Extended (ext3) Filesystem. Many Linux distributions ship kernels with this support preconfigured. The ext3 filesystem is essentially an ext2 filesystem with an added journal. Since it is in all other ways identical to the ext2 system, it is both forward and backward compatible with ext2—all ext2 utilities work with ext3 filesystems. When the kernel interacts with an ext3 filesystem, writes to disk are first written to a log or journal before they are written to disk. This slows down writes to the filesystem, but reduces the risk of data corruption in the event of a power outage. It also speeds up reboots after a system unexpectedly loses power. When rebooting with an ext2 filesystem, the fsck utility scans the entire disk to ensure that all data blocks are listed as either used or free, that each data block is claimed by only one file or directory, and that all files are available in the directory tree. When rebooting an ext3 filesystem using a supported kernel, it need only check the journal and complete any tasks that were left uncompleted.

To change an ext2 filesystem into an ext3 filesystem, simply add a journal using the tune2fs utility with the -j option on the unmounted device. If the filesystem is listed in /etc/fstab, change its specified filesystem from ext2 to ext3, or auto (mountd will automatically detect the right system).

You can specify the level of journaling the kernel should use in the mount options field (or using mount -o). There are three data options:

data=journal

Log all filesystem data and metadata changes. All changes to the filesystem are written twice, once to the journal and once to the filesystem itself. This is the slowest but safest mode.

data=ordered

Log filesystem metadata. Flush data updates to disk before changing metadata. This is the default mode. This slows writes a small amount, but ensures the filesystem is always in sync with changes to its metadata.

data=writeback

Log filesystem metadata. Use the ext2 write process to write data changes. This is the fastest journaling mode. While it maintains filestructure integrity, the contents of files may contain old, stale data when the filesystem is restarted from an unexpected shutdown.

The last field in the /etc/fstab entry specifies at what point in the boot process the filesystem should be verified with fsck. It should never need to be checked because journaling ensures filesystem integrity. You can set this field to 0. You can also turn off the automatic check of the filesystem that normally occurs every 20th time the system is mounted using tune2fs -i 0 -c 0.

Although not covered in this edition of Linux in a Nutshell, Linux supports three other open source journaling filesystems: IBM's Journaled Filesystem (JFS), SGI's Extensible Filesystem (XFS), and the Naming System Venture's Reiser Filesystem (ReiserFS). In some situations these can be faster than ext3. Some Linux distributions use these alternative filesystems by default.

debugfs | Debug ext2 filesystem.
dosfsck | Check and repair a DOS or VFAT filesystem.
dumpe2fs | Print information about superblock and blocks group.
e2fsck | Check and repair an ext2 filesystem.
e2image | Store disaster recovery data for an ext2 filesystem.
fdformat | Format floppy disk.
fsck | Another name for e2fsck.
fsck.ext2 | Check and repair an ext2 filesystem.
fsck.minix | Check and repair a MINIX filesystem.
fuser | List processes using a filesystem.
mke2fs | Make a new ext2 filesystem.
mkfs | Make new filesystem.
mkfs.ext2 | Another name for mke2fs.
mkfs.ext3 | Yet another name for mke2fs.
mkfs.minix | Make new MINIX filesystem.
mklost+found | Make lost+found directory.
mkraid | Set up a RAID device.
mkswap | Designate swap space.
mount | Mount a filesystem.
raidstart | Activate a RAID device.
raidstop | Turn off a RAID device.
rdev | Describe or change values for root filesystem.
resize2fs | Enlarge or shrink an ext2 filesystem.
rootflags | List or set flags to use in mounting root filesystem.
showmount | List exported directories.
swapoff | Cease using device for swapping.
swapon | Begin using device for swapping.
sync | Write filesystem buffers to disk.
tune2fs | Manage an ext2 filesystem.
umount | Unmount a filesystem.

2.1.8 Managing the Kernel

depmod | Create module dependency listing.
insmod | Install new kernel module.
lsmod | List kernel modules.
modinfo | Print kernel module information.
modprobe | Load new module and its dependent modules.
rmmod | Remove module.
sysctl | Examine or modify kernel parameters at runtime.

2.1.9 Networking

chat | Establish dial-up IP connections.
dip | Establish dial-up IP connections.
gdc | Administer gated routing daemon.
ifconfig | Manage network interfaces.
ipchains | Administer firewall facilities (2.2 kernel).
iptables | Administer firewall facilities (2.4 kernel).
named | Translate between domain names and IP addresses.
nameif | Assign names to network devices.
netstat | Print network status.
nfsstat | Print statistics for NFS and RPC.
nsupdate | Submit dynamic DNS update requests.
portmap | Map daemons to ports.
rarp | Manage RARP table.
route | Manage routing tables.
routed | Dynamically keep routing tables up to date.
rpcinfo | Report RPC information.
ruptime | Check how long remote system has been up.
rwho | Show who is logged into remote system.
traceroute | Trace network route to remote host.

2.1.10 Printing

checkpc | Examine and repair printer settings.
lpc | Control line printer.
tunelp | Tune the printer parameters.

2.1.11 Security and System Integrity

badblocks | Search for bad blocks.
chroot | Change root directory.

2.1.12 Starting and Stopping the System

bootpd | Internet Boot Protocol daemon.
bootpgw | Internet Boot Protocol gateway.
bootptest | Test bootpd.
halt | Stop or shut down system.
init | Change runlevel.
reboot | Shut down, then reboot system.
runlevel | Print system runlevel.
shutdown | Shut down system.
telinit | Change the current runlevel.
uptime | Display uptimes of local machines.

2.1.13 System Activity and Process Management

A number of additional commands in Chapter 3 are particularly useful in controlling processes, including kill, killall, killall5, pidof, ps, and who.

fuser | Identify processes using file or filesystem.
ipcrm | Remove interprocess communication message queue, semaphore array, or shared memory segment.
ipcs | Print interprocess communication information.
renice | Change the priority of running processes.
top | Show most CPU-intensive processes.
vmstat | Print virtual memory statistics and process statistics.

2.1.14 Users

chpasswd | Change multiple passwords.
groupadd | Add a new group.
groupdel | Delete a group
groupmod | Modify groups.
grpck | Check the integrity of group system files.
grpconv | Convert group file to shadow group file.
lastlog | Generate report of last user login times.
newusers | Add new users in a batch.
pwck | Check the integrity of password system files.
pwconv | Convert password file to shadow passwords.
rusers | Print who-style information on remote machines.
rwall | Print a message to remote users.
useradd | Add a new user.
userdel | Delete a user and that user's home directory.
usermod | Modify a user's information.
w | List logged-in users.
wall | Write to all users.
whoami | Show how you are currently logged in.

2.1.15 Miscellaneous

anacron | Schedule commands for periodic execution.
atrun | Schedule commands for later execution.
cron | Schedule commands for specific times.
dmesg | Print bootup messages after the system is up.
ldconfig | Update library links and do caching.
logger | Send messages to the system logger.
logrotate | Compress and rotate system logs.
run-parts | Run all scripts in a directory.


2.2 Overview of Networking

Networks connect computers so that the different systems can share information. For users and system administrators, Unix systems have traditionally provided a set of simple but valuable network services that let you check whether systems are running, refer to files residing on remote systems, communicate via electronic mail, and so on.

For most commands to work over a network, each system must be continuously running a server process in the background, silently waiting to handle the user's request. This kind of process is called a daemon. Common examples, on which you rely for the most basic functions of your Linux system, are named (which translates between numeric IP addresses and more human-readable alphanumeric names), lpd (which sends documents to a printer, possibly over a network), and ftpd (which allows you to connect to another machine via ftp).

Most Unix networking commands are based on Internet protocols. These are standardized ways of communicating across a network on hierarchical layers. The protocols range from addressing and packet routing at a relatively low layer to finding users and executing user commands at a higher layer.

The basic user commands that most systems support over Internet protocols are generally called TCP/IP commands, named after the two most common protocols. You can use all of these commands to communicate with other Unix systems besides Linux systems. Many can also be used to communicate with non-Unix systems, as a wide variety of systems support TCP/IP.

This section also covers NFS and NIS—which allow for transparent file and information sharing across networks—and sendmail.

2.2.1 TCP/IP Administration

ftpd | Server for file transfers.
gated | Manage routing tables between networks.
host | Print host and zone information.
ifconfig | Configure network interface parameters.
named | Translate between domain names and IP addresses.
netstat | Print network status.
nslookup | Query domain name servers.
ping | Check that a remote host is online and responding.
pppd | Create PPP serial connection.
rdate | Notify time server that date has changed.
route | Manage routing tables.
routed | Dynamically keep routing tables up to date.
slattach | Attach serial lines as network interfaces.
sshd | Server for secure shell connections.
telnetd | Server for Telnet sessions from remote hosts.
tftpd | Server for restricted set of file transfers.

2.2.2 NFS and NIS Administration

domainname | Set or display name of current NIS domain.
makedbm | Rebuild NIS databases.
portmap | DARPA port to RPC program number mapper.
rpcinfo | Report RPC information.
ypbind | Connect to NIS server.
ypcat | Print values in NIS database.
ypinit | Build new NIS databases.
ypmatch | Print value of one or more NIS keys.
yppasswd | Change user password in NIS database.
yppasswdd | Update NIS database in response to yppasswd.
yppoll | Determine version of NIS map at NIS server.
yppush | Propagate NIS map.
ypserv | NIS server daemon.
ypset | Point ypbind at a specific server.
yptest | Check NIS configuration.
ypwhich | Display name of NIS server or map master.
ypxfr | Transfer NIS database from server to local host.


Chapter 10. The Emacs Editor

The Emacs editor is found on many Unix systems, including Linux, because it is a popular alternative to vi. Many versions are available. This book documents GNU Emacs, which is available from the Free Software Foundation in Cambridge, MA. For more information, see the O'Reilly book Learning GNU Emacs.

Emacs is much more than "just an editor"—in fact, it provides a fully integrated user environment. From within Emacs you can issue individual shell commands, or open a window where you can work in the shell, read and send mail, read news, access the Internet, write and test programs, and maintain a calendar. To fully describe Emacs would require more space than we have available. In this chapter, therefore, we focus on the editing capabilities of Emacs.

To start an Emacs editing session, type:

emacs

You can also specify one or more files for Emacs to open when it starts:

emacs files


10.1 Emacs Concepts

This section describes some Emacs terminology that may be unfamiliar if you haven't used Emacs before.

10.1.1 Modes

One of the features that makes Emacs popular is its editing modes. The modes set up an environment designed for the type of editing you are doing, with features like having appropriate key bindings available, and automatically indenting according to standard conventions for that type of document. There are two types of modes, major and minor. The major modes include modes for various programming languages like C or Perl, for text processing (e.g., SGML or even straight text), and many more. One particularly useful major mode is Dired (Directory Editor), which has commands that let you manage directories. Minor modes set or unset features that are independent of the major mode, such as auto-fill (which controls word wrapping), insert versus overwrite, and auto-save. For a full discussion of modes, see Learning GNU Emacs or the Emacs Info documentation system (C-h i).

10.1.2 Buffer and Window

When you open a file in Emacs, the file is put into a buffer so you can edit it. If you open another file, that file goes into another buffer. The view of the buffer contents that you have at any point in time is called a window. For a small file, the window might show the entire file; for a large file, it shows only a portion of a file. Emacs allows multiple windows to be open at the same time, to display the contents of different buffers or different portions of a single buffer.

10.1.3 Point and Mark

When you are editing in Emacs, the position of the cursor is known as point. You can set a mark at another place in the text to operate on the region between point and mark. This is a very useful feature for such operations as deleting or moving an area of text.

10.1.4 Kill and Yank

Emacs uses the terms kill and yank for the concepts more commonly known today as cut and paste. You cut text in Emacs by killing it, and paste it by yanking it back. If you do multiple kills in a row, you can yank them back all at once.


10.2 Typical Problems

A common problem with Emacs is that the Del or Backspace key does not delete the character before the cursor, as it should, but instead invokes a help prompt. This problem is caused by an incompatible terminal setup file. A fairly robust fix is to create a file named .emacs in your home directory (or edit one that's already there) and add the following lines:

(keyboard-translate ?\C-h ?\C-?)

(keyboard-translate ?\C-\\ ?\C-h)

Now the Del or Backspace kill should work, and you can invoke help by pressing C-\ (an arbitrarily chosen key sequence).

Another potential problem is that on some systems, C-s causes the terminal to hang. This is due to an old-fashioned handshake protocol between the terminal and the system. You can restart the terminal by pressing C-q, but that doesn't help you enter commands that contain the sequence C-s. The solution (aside from using a more modern dial-in protocol) is to create new key bindings that replace C-s or to enter those commands as M-x command-name. This is not specifically an Emacs problem, but it can cause problems when you run Emacs in a terminal window because C-s and C-q are commonly used Emacs key sequences.


10.3 Notes on the Tables

Emacs commands use the Ctrl key and the Meta key. Most modern terminals provide a key named Alt that functions as a Meta key. In this section, the notation C- indicates that you should hold down the Ctrl key and press the character that follows, while M- indicates the same for the Meta or Alt key. As an alternative to Meta or Alt, you can press the Esc key, release it, and press the character. You might want to do this if you have problems with controlling windows capturing the Alt key (which sometimes happens).

In the command tables that follow, the first column lists the keystroke and the last column describes it. When there is a middle column, it lists the command name. The command can be executed by typing M-x followed by the command name; you have to do this when the binding is listed as "(none)". If you're unsure of the full command name, you can type a space, tab, or carriage return, and Emacs will list possible completions of what you've typed so far.

Because Emacs is such a comprehensive editor, containing hundreds of commands, some commands must be omitted for the sake of preserving a "quick" reference. You can browse the full command set by typing C-h (for help) and then b to get a list of the key bindings,[1] or M-x followed by a space or tab to get the command names.

[1] If you want to learn to create your own key bindings, see Learning GNU Emacs (O'Reilly).

10.3.1 Absolutely Essential Commands

If you're just getting started with Emacs, here's a short list of the most important commands to know:

Binding | Action
C-h | Enter the online help system.
C-x C-s | Save the file.
C-x C-c | Exit Emacs.
C-x u | Undo last edit (can be repeated).
C-g | Get out of current command operation.
C-p | Up by one line.
C-n | Down by one line.
C-f | Forward by one character.
C-b | Back by one character.
C-v | Forward by one screen.
M-v | Backward by one screen.
C-s | Search forward for characters.
C-r | Search backward for characters.
C-d | Delete current character.
Del | Delete previous character.
Backspace | Delete previous character.


10.4 Summary of Commands by Group

Tables list keystrokes, command name, and description. C- indicates the Ctrl key; M- indicates the Meta key.

10.4.1 File Handling Commands

Binding | Command | Action
C-x C-f | find-file | Find file and read it.
C-x C-v | find-alternate-file | Read another file; replace the one read currently in the buffer.
C-x i | insert-file | Insert file at cursor position.
C-x C-s | save-buffer | Save file. (If terminal hangs, C-q restarts.)
C-x C-w | write-file | Write buffer contents to file.
C-x C-c | save-buffers-kill-emacs | Exit Emacs.
C-z | suspend-emacs | Suspend Emacs (use exit or fg to restart).

10.4.2 Cursor Movement Commands

In addition to the key bindings shown in this table, you can use the arrow keys to move around in Emacs. When you are running Emacs in a graphical display environment (e.g., in the X Window System), you can also use the mouse for operations such as moving the cursor or selecting text.

Binding | Command | Action
C-f | forward-char | Move forward one character (right).
C-b | backward-char | Move backward one character (left).
C-p | previous-line | Move to previous line (up).
C-n | next-line | Move to next line (down).
M-f | forward-word | Move one word forward.
M-b | backward-word | Move one word backward.
C-a | beginning-of-line | Move to beginning of line.
C-e | end-of-line | Move to end of line.
M-a | backward-sentence | Move backward one sentence.
M-e | forward-sentence | Move forward one sentence.
M-{ | backward-paragraph | Move backward one paragraph.
M-} | forward-paragraph | Move forward one paragraph.
C-v | scroll-up | Move forward one screen.
M-v | scroll-down | Move backward one screen.
C-x [ | backward-page | Move backward one page.
C-x ] | forward-page | Move forward one page.
M-> | end-of-buffer | Move to end-of-file.
M-< | beginning-of-buffer | Move to beginning of file.
(none) | goto-line | Go to line n of file.
(none) | goto-char | Go to character n of file.
C-l | recenter | Redraw screen with current line in the center.
M-n | digit-argument | Repeat the next command n times.
C-u n | universal-argument | Repeat the next command n times.

10.4.3 Deletion Commands

Binding | Command | Action
Del | backward-delete-char | Delete previous character.
C-d | delete-char | Delete character under cursor.
M-Del | backward-kill-word | Delete previous word.
M-d | kill-word | Delete the word the cursor is on.
C-k | kill-line | Delete from cursor to end-of-line.
M-k | kill-sentence | Delete sentence the cursor is on.
C-x Del | backward-kill-sentence | Delete previous sentence.
C-y | yank | Restore what you've deleted.
C-w | kill-region | Delete a marked region (see Section 10.4.4).
(none) | backward-kill-paragraph | Delete previous paragraph.
(none) | kill-paragraph | Delete from the cursor to the end of the paragraph.

10.4.4 Paragraphs and Regions

Binding | Command | Action
C-@ | set-mark-command | Mark the beginning (or end) of a region.
C-Space | (Same as preceding) | (Same as preceding)
C-x C-p | mark-page | Mark page.
C-x C-x | exchange-point-and-mark | Exchange location of cursor and mark.
C-x h | mark-whole-buffer | Mark buffer.
M-q | fill-paragraph | Reformat paragraph.
(none) | fill-region | Reformat individual paragraphs within a region.
M-h | mark-paragraph | Mark paragraph.
M-{ | backward-paragraph | Move backward one paragraph.
M-} | forward-paragraph | Move forward one paragraph.
(none) | backward-kill-paragraph | Delete previous paragraph.
(none) | kill-paragraph | Delete from the cursor to the end of the paragraph.

10.4.5 Stopping and Undoing Commands

Binding | Command | Action
C-g | keyboard-quit | Abort current command.
C-x u | advertised-undo | Undo last edit (can be done repeatedly).
(none) | revert-buffer | Restore buffer to the state it was in when the file was last saved (or auto-saved).

10.4.6 Transposition Commands

Binding | Command | Action
C-t | transpose-chars | Transpose two letters.
M-t | transpose-words | Transpose two words.
C-x C-t | transpose-lines | Transpose two lines.
(none) | transpose-sentences | Transpose two sentences.
(none) | transpose-paragraphs | Transpose two paragraphs.

10.4.7 Capitalization Commands

Binding | Command | Action
M-c | capitalize-word | Capitalize first letter of word.
M-u | upcase-word | Uppercase word.
M-l | downcase-word | Lowercase word.
M- - M-c | negative-argument; capitalize-word | Capitalize previous word.
M- - M-u | negative-argument; upcase-word | Uppercase previous word.
M- - M-l | negative-argument; downcase-word | Lowercase previous word.
(none) | capitalize-region | Capitalize initial letters in region.
C-x C-u | upcase-region | Uppercase region.
C-x C-l | downcase-region | Lowercase region.

10.4.8 Incremental Search Commands

Binding | Command | Action
C-s | isearch-forward | Start or repeat incremental search forward.
C-r | isearch-backward | Start or repeat incremental search backward.
Return | (none) | Exit a successful search.
C-g | keyboard-quit | Cancel incremental search; return to starting point.
Del | (none) | Delete incorrect character of search string.
M-C-r | isearch-backward-regexp | Incremental search backward for regular expression.
M-C-s | isearch-forward-regexp | Incremental search forward for regular expression.

10.4.9 Word Abbreviation Commands

Binding | Command | Action
(none) | abbrev-mode | Enter (or exit) word abbreviation mode.
C-x a - | inverse-add-global-abbrev | Define previous word as global (mode-independent) abbreviation.
C-x a i l | inverse-add-mode-abbrev | Define previous word as mode-specific abbreviation.
(none) | unexpand-abbrev | Undo the last word abbreviation.
(none) | write-abbrev-file | Write the word abbreviation file.
(none) | edit-abbrevs | Edit the word abbreviations.
(none) | list-abbrevs | View the word abbreviations.
(none) | kill-all-abbrevs | Kill abbreviations for this session.

10.4.10 Buffer Manipulation Commands

Binding | Command | Action
C-x b | switch-to-buffer | Move to specified buffer.
C-x C-b | list-buffers | Display buffer list.
C-x k | kill-buffer | Delete specified buffer.
(none) | kill-some-buffers | Ask about deleting each buffer.
(none) | rename-buffer | Change buffer name to specified name.
C-x s | save-some-buffers | Ask whether to save each modified buffer.

10.4.11 Window Commands

Binding | Command | Action
C-x 2 | split-window-vertically | Divide the current window in two vertically, resulting in one window on top of the other.
C-x 3 | split-window-horizontally | Divide the current window in two horizontally, resulting in two side-by-side windows.
C-x > | scroll-right | Scroll the window right.
C-x < | scroll-left | Scroll the window left.
C-x o | other-window | Move to the other window.
C-x 0 | delete-window | Delete current window.
C-x 1 | delete-other-windows | Delete all windows but this one.
(none) | delete-windows-on | Delete all windows on a given buffer.
C-x ^ | enlarge-window | Make window taller.
(none) | shrink-window | Make window shorter.
C-x } | enlarge-window- horizontally | Make window wider.
C-x { | shrink-window- horizontally | Make window narrower.
M-C-v | scroll-other-window | Scroll other window.
C-x 4 f | find-file-other-window | Find a file in the other window.
C-x 4 b | switch-to-buffer-other-window | Select a buffer in the other window.
C-x 5 f | find-file-other-frame | Find a file in a new frame.
C-x 5 b | switch-to-buffer-other-frame | Select a buffer in another frame.
(none) | compare-windows | Compare two buffers; show first difference.

10.4.12 Special Shell Mode Characters

The following table shows commands that can be used in Shell mode. To enter Shell mode, run the command M-x shell.

Binding | Command | Action
C-c C-c | interrupt-shell-subjob | Terminate the current job.
C-c C-d | shell-send-eof | End-of-file character.
C-c C-u | kill-shell-input | Erase current line.
C-c C-w | backward-kill-word | Erase the previous word.
C-c C-z | stop-shell-subjob | Suspend the current job.

10.4.13 Indentation Commands

Binding | Command | Action
C-x . | set-fill-prefix | Prepend each line in paragraph with characters from beginning of line up to cursor column; cancel prefix by typing this command in column 1.
(none) | indented-text-mode | Major mode: each tab defines a new indent for subsequent lines.
(none) | text-mode | Exit indented text mode; return to text mode.
M-C-\ | indent-region | Indent a region to match first line in region.
M-m | back-to-indentation | Move cursor to first character on line.
M-^ | delete-indentation | Join this line to the previous line.
M-C-o | split-line | Split line at cursor; indent to column of cursor.
(none) | fill-individual- paragraphs | Reformat indented paragraphs, keeping indentation.

10.4.14 Centering Commands

Binding | Command | Action
(none) | center-line | Center line that cursor is on.
(none) | center-paragraph | Center paragraph that cursor is on.
(none) | center-region | Center currently defined region.

10.4.15 Macro Commands

Binding | Command | Action
C-x ( | start-kbd-macro | Start macro definition.
C-x ) | end-kbd-macro | End macro definition.
C-x e | call-last-kbd-macro | Execute last macro defined.
M-n C-x e | digit-argument and call-last-kbd-macro | Execute last macro defined n times.
C-u C-x ( | start-kbd-macro | Execute last macro defined, then add keystrokes.
(none) | name-last-kbd-macro | Name last macro you created (before saving it).
(none) | insert-last-keyboard- macro | Insert the macro you named into a file.
(none) | load-file | Load macro files you've saved.
(none) | macroname | Execute a keyboard macro you've saved.
C-x q | kbd-macro-query | Insert a query in a macro definition.
C-u C-x q | (none) | Insert a recursive edit in a macro definition.
M-C-c | exit-recursive-edit | Exit a recursive edit.

10.4.16 Detail Information Help Commands

Binding | Command | Action
C-h a | command-apropos | What commands involve this concept?
(none) | apropos | What commands, functions, and variables involve this concept?
C-h c | describe-key-briefly | What command does this keystroke sequence run?
C-h b | describe-bindings | What are all the key bindings for this buffer?
C-h k | describe-key | What command does this keystroke sequence run, and what does it do?
C-h l | view-lossage | What are the last 100 characters I typed?
C-h w | where-is | What is the key binding for this command?
C-h f | describe-function | What does this function do?
C-h v | describe-variable | What does this variable mean, and what is its value?
C-h m | describe-mode | Tell me about the mode the current buffer is in.
C-h s | describe-syntax | What is the syntax table for this buffer?

10.4.17 Help Commands

Binding | Command | Action
C-h t | help-with-tutorial | Run the Emacs tutorial.
C-h i | info | Start the Info documentation reader.
C-h n | view-emacs-news | View news about updates to Emacs.
C-h C-c | describe-copying | View the Emacs General Public License.
C-h C-d | describe-distribution | View information on ordering Emacs from the FSF.
C-h C-w | describe-no-warranty | View the (non)warranty for Emacs.


10.5 Summary of Commands by Key

Emacs commands are presented next in two alphabetical lists. Tables list keystrokes, command name, and description. C- indicates the Ctrl key; M- indicates the Meta key.

10.5.1 Control-Key Sequences

Binding | Command | Action
C-@ | set-mark-command | Mark the beginning (or end) of a region.
C-Space | (Same as preceding) | (Same as preceding)
C-] | abort-recursive-edit | Exit recursive edit and exit query-replace.
C-a | beginning-of-line | Move to beginning of line.
C-b | backward-char | Move backward one character (left).
C-c C-c | interrupt-shell-subjob | Terminate the current job.
C-c C-d | shell-send-eof | End-of-file character.
C-c C-u | kill-shell-input | Erase current line.
C-c C-w | backward-kill-word | Erase previous word.
C-c C-z | stop-shell-subjob | Suspend current job.
C-d | delete-char | Delete character under cursor.
C-e | end-of-line | Move to end of line.
C-f | forward-char | Move forward one character (right).
C-g | keyboard-quit | Abort current command.
C-h | help-command | Enter the online help system.
C-h a | command-apropos | What commands involve this concept?
C-h b | describe-bindings | What are all the key bindings for this buffer?
C-h c | describe-key-briefly | What command does this keystroke sequence run?
C-h C-c | describe-copying | View the Emacs General Public License.
C-h C-d | describe-distribution | View information on ordering Emacs from the FSF.
C-h C-w | describe-no-warranty | View the (non)warranty for Emacs.
C-h f | describe-function | What does this function do?
C-h i | info | Start the Info documentation reader.
C-h k | describe-key | What command does this keystroke sequence run, and what does it do?
C-h l | view-lossage | What are the last 100 characters I typed?
C-h m | describe-mode | Tell me about the mode the current buffer is in.
C-h n | view-emacs-news | View news about updates to Emacs.
C-h s | describe-syntax | What is the syntax table for this buffer?
C-h t | help-with-tutorial | Run the Emacs tutorial.
C-h v | describe-variable | What does this variable mean, and what is its value?
C-h w | where-is | What is the key binding for this command?
C-k | kill-line | Delete from cursor to end-of-line.
C-l | recenter | Redraw screen with current line in the center.
C-n | next-line | Move to next line (down).
C-p | previous-line | Move to previous line (up).
C-q | quoted-insert | Insert next character typed. Useful for inserting a control character.
C-r | isearch-backward | Start or repeat nonincremental search backward.
C-r | (none) | Enter recursive edit (during query replace).
C-s | isearch-forward | Start or repeat nonincremental search forward.
C-t | transpose-chars | Transpose two letters.
C-u n | universal-argument | Repeat the next command n times.
C-u C-x ( | start-kbd-macro | Execute last macro defined, then add keystrokes.
C-u C-x q | (none) | Insert recursive edit in a macro definition.
C-v | scroll-up | Move forward one screen.
C-w | kill-region | Delete a marked region.
C-x ( | start-kbd-macro | Start macro definition.
C-x ) | end-kbd-macro | End macro definition.
C-x [ | backward-page | Move backward one page.
C-x ] | forward-page | Move forward one page.
C-x ^ | enlarge-window | Make window taller.
C-x { | shrink-window-horizontally | Make window narrower.
C-x } | enlarge-window-horizontally | Make window wider.
C-x < | scroll-left | Scroll the window left.
C-x > | scroll-right | Scroll the window right.
C-x . | set-fill-prefix | Prepend each line in paragraph with characters from beginning of line up to cursor column; cancel prefix by typing this command in column 1.
C-x 0 | delete-window | Delete current window.
C-x 1 | delete-other-windows | Delete all windows but this one.
C-x 2 | split-window-vertically | Divide current window in two vertically, resulting in one window on top of the other.
C-x 3 | split-window-horizontally | Divide current window in two horizontally, resulting in two side-by-side windows.
C-x 4 b | switch-to-buffer-other-window | Select a buffer in the other window.
C-x 4 f | find-file-other-window | Find a file in the other window.
C-x 5 b | switch-to-buffer-other-frame | Select a buffer in another frame.
C-x 5 f | find-file-other-frame | Find a file in another frame.
C-x a - | inverse-add-global-abbrev | Define previous word as global (mode-independent) abbreviation.
C-x a i l | inverse-add-mode-abbrev | Define previous word as mode-specific abbreviation.
C-x b | switch-to-buffer | Move to the buffer specified.
C-x C-b | list-buffers | Display the buffer list.
C-x C-c | save-buffers-kill-emacs | Exit Emacs.
C-x C-f | find-file | Find file and read it.
C-x C-l | downcase-region | Lowercase region.
C-x C-p | mark-page | Place cursor and mark around whole page.
C-x C-q | (none) | Toggle read-only status of buffer.
C-x C-s | save-buffer | Save file. (If terminal hangs, C-q restarts.)
C-x C-t | transpose-lines | Transpose two lines.
C-x C-u | upcase-region | Uppercase region.
C-x C-v | find-alternate-file | Read an alternate file, replacing the one currently in the buffer.
C-x C-w | write-file | Write buffer contents to file.
C-x C-x | exchange-point-and-mark | Exchange location of cursor and mark.
C-x Del | backward-kill- sentence | Delete previous sentence.
C-x e | call-last-kbd-macro | Execute last macro defined.
C-x h | mark-whole-buffer | Place cursor and mark around whole buffer.
C-x i | insert-file | Insert file at cursor position.
C-x k | kill-buffer | Delete the buffer specified.
C-x o | other-window | Move to the other window.
C-x q | kbd-macro-query | Insert a query in a macro definition.
C-x s | save-some-buffers | Ask whether to save each modified buffer.
C-x u | advertised-undo | Undo last edit (can be done repeatedly).
C-y | yank | Restore killed text.
C-z | suspend-emacs | Suspend Emacs (use exit or fg to restart).

10.5.2 Meta-Key Sequences

Binding | Command | Action
M-- M-c | negative-argument; capitalize-word | Capitalize previous word.
M-- M-l | negative-argument; downcase-word | Lowercase previous word.
M-- M-u | negative-argument; upcase-word | Uppercase previous word.
M-$ | spell-word | Check spelling of word after cursor.
M-% | query-replace | Search for and replace a string.
M-! | shell-command | Prompt for a shell command and run it.
M-< | beginning-of-buffer | Move to beginning of file.
M-> | end-of-buffer | Move to end-of-file.
M-{ | backward-paragraph | Move backward one paragraph.
M-} | forward-paragraph | Move forward one paragraph.
M-^ | delete-indentation | Join this line to the previous one.
M-n | digit-argument | Repeat the next command n times.
M-n C-x e | digit-argument; call-last-kbd-macro | Execute the last defined macro n times.
M-a | backward-sentence | Move backward one sentence.
M-b | backward-word | Move one word backward.
M-c | capitalize-word | Capitalize first letter of word.
M-C-\ | indent-region | Indent a region to match first line in region.
M-C-c | exit-recursive-edit | Exit a recursive edit.
M-C-o | split-line | Split line at cursor; indent to column of cursor.
M-C-r | isearch-backward-regexp | Incremental search backward for regular expression.
M-C-s | isearch-forward-regexp | Incremental search forward for regular expression.
M-C-v | scroll-other-window | Scroll other window.
M-d | kill-word | Delete word that cursor is on.
M-Del | backward-kill-word | Delete previous word.
M-e | forward-sentence | Move forward one sentence.
M-f | forward-word | Move one word forward.
(none) | fill-region | Reformat individual paragraphs within a region.
M-h | mark-paragraph | Place cursor and mark around whole paragraph.
M-k | kill-sentence | Delete sentence that cursor is on.
M-l | downcase-word | Lowercase word.
M-m | back-to-indentation | Move cursor to first nonblank character on line.
M-q | fill-paragraph | Reformat paragraph.
M-t | transpose-words | Transpose two words.
M-u | upcase-word | Uppercase word.
M-v | scroll-down | Move backward one screen.
M-x | (none) | Execute a command by typing its name.


10.6 Summary of Commands by Name

The following Emacs commands are presented alphabetically by command name. Use M-x to access the command name. Tables list command name, keystroke, and description. C- indicates the Ctrl key; M- indicates the Meta key.

Command | Binding | Action
macroname | (none) | Execute a keyboard macro you've saved.
abbrev-mode | (none) | Enter (or exit) word abbreviation mode.
abort-recursive-edit | C-] | Exit recursive edit and query replace.
advertised-undo | C-x u | Undo last edit (can be done repeatedly).
apropos | (none) | What functions and variables involve this concept?
back-to-indentation | M-m | Move cursor to first nonblank character on line.
backward-char | C-b | Move backward one character (left).
backward-delete-char | Del | Delete previous character.
backward-kill-paragraph | (none) | Delete previous paragraph.
backward-kill-sentence | C-x Del | Delete previous sentence.
backward-kill-word | C-c C-w | Delete previous word.
backward-kill-word | M-Del | Delete previous word.
backward-page | C-x [ | Move backward one page.
backward-paragraph | M-{ | Move backward one paragraph.
backward-sentence | M-a | Move backward one sentence.
backward-word | M-b | Move backward one word.
beginning-of-buffer | M-< | Move to beginning of file.
beginning-of-line | C-a | Move to beginning of line.
call-last-kbd-macro | C-x e | Execute last macro defined.
capitalize-region | (none) | Capitalize region.
capitalize-word | M-c | Capitalize first letter of word.
center-line | (none) | Center line that cursor is on.
center-paragraph | (none) | Center paragraph that cursor is on.
center-region | (none) | Center currently defined region.
command-apropos | C-h a | What commands involve this concept?
compare-windows | (none) | Compare two buffers; show first difference.
delete-char | C-d | Delete character under cursor.
delete-indentation | M-^ | Join this line to previous one.
delete-other-windows | C-x 1 | Delete all windows but this one.
delete-window | C-x 0 | Delete current window.
delete-windows-on | (none) | Delete all windows on a given buffer.
describe-bindings | C-h b | What are all the key bindings for in this buffer?
describe-copying | C-h C-c | View the Emacs General Public License.
describe-distribution | C-h C-d | View information on ordering Emacs from the FSF.
describe-function | C-h f | What does this function do?
describe-key | C-h k | What command does this keystroke sequence run, and what does it do?
describe-key-briefly | C-h c | What command does this keystroke sequence run?
describe-mode | C-h m | Tell me about the mode the current buffer is in.
describe-no-warranty | C-h C-w | View the (non)warranty for Emacs.
describe-syntax | C-h s | What is the syntax table for this buffer?
describe-variable | C-h v | What does this variable mean, and what is its value?
digit-argument | M-n | Repeat next command n times.
downcase-region | C-x C-l | Lowercase region.
downcase-word | M-l | Lowercase word.
edit-abbrevs | (none) | Edit word abbreviations.
end-kbd-macro | C-x ) | End macro definition.
end-of-buffer | M-> | Move to end-of-file.
end-of-line | C-e | Move to end-of-line.
enlarge-window | C-x ^ | Make window taller.
enlarge-window-horizontally | C-x } | Make window wider.
exchange-point-and-mark | C-x C-x | Exchange location of cursor and mark.
exit-recursive-edit | M-C-c | Exit a recursive edit.
fill-individual-paragraphs | (none) | Reformat indented paragraphs, keeping indentation.
fill-paragraph | M-q | Reformat paragraph.
fill-region | (none) | Reformat individual paragraphs within a region.
find-alternate-file | C-x C-v | Read an alternate file, replacing the one currently in the buffer.
find-file | C-x C-f | Find file and read it.
find-file-other-frame | C-x 5 f | Find a file in another frame.
find-file-other-window | C-x 4 f | Find a file in another window.
forward-char | C-f | Move forward one character (right).
forward-page | C-x ] | Move forward one page.
forward-paragraph | M-} | Move forward one paragraph.
forward-sentence | M-e | Move forward one sentence.
forward-word | M-f | Move forward one word.
goto-char | (none) | Go to character n of file.
goto-line | (none) | Go to line n of file.
help-command | C-h | Enter the online help system.
help-with-tutorial | C-h t | Run the Emacs tutorial.
indent-region | M-C-\ | Indent a region to match first line in region.
indented-text-mode | (none) | Major mode: each tab defines a new indent for subsequent lines.
info | C-h i | Start the Info documentation reader.
insert-file | C-x i | Insert file at cursor position.
insert-last-keyboard-macro | (none) | Insert the macro you named into a file.
interrupt-shell-subjob | C-c C-c | Terminate the current job (shell mode).
inverse-add-global-abbrev | C-x a - | Define previous word as global (mode-independent) abbreviation.
inverse-add-mode-abbrev | C-x a i l | Define previous word as mode-specific abbreviation.
isearch-backward | C-r | Start incremental search backward.
isearch-backward-regexp | M-C-r | Same, but search for regular expression.
isearch-forward | C-s | Start incremental search forward.
isearch-forward-regexp | M-C-s | Same, but search for regular expression.
kbd-macro-query | C-x q | Insert a query in a macro definition.
keyboard-quit | C-g | Abort current command.
kill-all-abbrevs | (none) | Kill abbreviations for this session.
kill-buffer | C-x k | Delete the buffer specified.
kill-line | C-k | Delete from cursor to end-of-line.
kill-paragraph | (none) | Delete from cursor to end of paragraph.
kill-region | C-w | Delete a marked region.
kill-sentence | M-k | Delete sentence the cursor is on.
kill-shell-input | C-c C-u | Delete current line.
kill-some-buffers | (none) | Ask about deleting each buffer.
kill-word | M-d | Delete word the cursor is on.
list-abbrevs | (none) | View word abbreviations.
list-buffers | C-x C-b | Display buffer list.
load-file | (none) | Load macro files you've saved.
mark-page | C-x C-p | Place cursor and mark around whole page.
mark-paragraph | M-h | Place cursor and mark around whole paragraph.
mark-whole-buffer | C-x h | Place cursor and mark around whole buffer.
name-last-kbd-macro | (none) | Name last macro you created (before saving it).
negative-argument; capitalize-word | M-- M-c | Capitalize previous word.
negative-argument; downcase-word | M-- M-l | Lowercase previous word.
negative-argument; upcase-word | M-- M-u | Uppercase previous word.
next-line | C-n | Move to next line (down).
other-window | C-x o | Move to the other window.
previous-line | C-p | Move to previous line (up).
query-replace | M-% | Search for and replace a string.
query-replace-regexp | (none) | Query-replace a regular expression.
quoted-insert | C-q | Insert next character typed. Useful for inserting a control character.
recenter | C-l | Redraw screen, with current line in center.
rename-buffer | (none) | Change buffer name to specified name.
replace-regexp | (none) | Replace a regular expression unconditionally.
re-search-backward | (none) | Simple regular-expression search backward.
re-search-forward | (none) | Simple regular-expression search forward.
revert-buffer | (none) | Restore buffer to the state it was in when the file was last saved (or auto-saved).
save-buffer | C-x C-s | Save file. (If terminal hangs, C-q restarts.)
save-buffers-kill-emacs | C-x C-c | Exit Emacs.
save-some-buffers | C-x s | Ask whether to save each modified buffer.
scroll-down | M-v | Move backward one screen.
scroll-left | C-x < | Scroll the window left.
scroll-other-window | M-C-v | Scroll other window.
scroll-right | C-x > | Scroll the window right.
scroll-up | C-v | Move forward one screen.
set-fill-prefix | C-x . | Prepend each line in paragraph with characters from beginning of line up to cursor column; cancel prefix by typing this command in column 1.
set-mark-command | C-@ or C-Space | Mark the beginning (or end) of a region.
shell-command | M-! | Prompt for a shell command and run it.
shell-send-eof | C-c C-d | End-of-file character (shell mode).
shrink-window | (none) | Make window shorter.
shrink-window-horizontally | C-x { | Make window narrower.
spell-buffer | (none) | Check spelling of current buffer.
spell-region | (none) | Check spelling of current region.
spell-string | (none) | Check spelling of string typed in minibuffer.
spell-word | M-$ | Check spelling of word after cursor.
split-line | M-C-o | Split line at cursor; indent to column of cursor.
split-window-horizontally | C-x 3 | Divide current window horizontally into two.
split-window-vertically | C-x 2 | Divide current window vertically into two.
start-kbd-macro | C-x ( | Start macro definition.
stop-shell-subjob | C-c C-z | Suspend current job.
suspend-emacs | C-z | Suspend Emacs (use fg to restart).
switch-to-buffer | C-x b | Move to the buffer specified.
switch-to-buffer-other-frame | C-x 5 b | Select a buffer in another frame.
switch-to-buffer-other- window | C-x 4 b | Select a buffer in another window.
text-mode | (none) | Enter text mode.
transpose-chars | C-t | Transpose two characters.
transpose-lines | C-x C-t | Transpose two lines.
transpose-paragraphs | (none) | Transpose two paragraphs.
transpose-sentences | (none) | Transpose two sentences.
transpose-words | M-t | Transpose two words.
unexpand-abbrev | (none) | Undo the last word abbreviation.
universal-argument | C-u n | Repeat the next command n times.
upcase-region | C-x C-u | Uppercase region.
upcase-word | M-u | Uppercase word.
view-emacs-news | C-h n | View news about updates to Emacs.
view-lossage | C-h l | What are the last 100 characters I typed?
where-is | C-h w | What is the key binding for this command?
write-abbrev-file | (none) | Write the word abbreviation file.
write-file | C-x C-w | Write buffer contents to file.
yank | C-y | Restore what you've deleted.


Chapter 11. The vi Editor

vi is the classic screen-editing program for Unix. A number of enhanced versions exist, including nvi, vim, vile, and elvis. On Linux, the vi command is usually a link to one of these programs. The Emacs editor, covered in Chapter 10, has several vi modes that allow you to use the same commands covered in this chapter.

The vi editor operates in two modes, command mode and insert mode. The dual mode makes vi an attractive editor for users who separate text entry from editing. For users who edit as they type, the modeless editing of emacs can be more comfortable.

vi is based on an older line editor called ex. A user can invoke powerful editing capabilities within vi by typing a colon (:), entering an ex command, and pressing the Return key. Furthermore, you can place ex commands in a startup file called ~/.exrc, which vi reads at the beginning of your editing session. Because ex commands are still an important part of vi, they are also described in this chapter.

One of the most common versions of vi found on Linux systems is Bram Moolenaar's Vi IMproved, or vim. On some Linux distributions, vim is the default version of vi and runs when you invoke vi. vim changes some of the basic features of vi, most notoriously changing the undo key to support multiple levels of undo. While seasoned users of vi find vim's changes disturbing, those new to vi find vim's extensive features attractive.

Fully documenting vim is beyond the scope of this chapter, but we do cover some of its most commonly used options and features. Beyond what we cover here, vim offers enhanced support to programmers through an integrated build and debugging process, syntax highlighting, extended ctags support, and support for Perl and Python, as well as GUI fonts and menus, function key mapping, independent mapping for each mode, and more. Fortunately, vim comes with a powerful help program you can use to learn more about the things we just couldn't fit into this chapter.

For more information, see the O'Reilly book Learning the vi Editor.


11.1 Review of vi Operations

This section provides a review of the following:

  • Command-line options

  • vi modes

  • Syntax of vi commands

  • Status-line commands

11.1.1 Command Mode

Once the file is opened, you are in command mode. From command mode, you can:

  • Invoke insert mode

  • Issue editing commands

  • Move the cursor to a different position in the file

  • Invoke ex commands

  • Invoke a Linux shell

  • Save or exit the current version of the file

11.1.2 Insert Mode

In insert mode, you can enter new text in the file. Press the Esc or Ctrl-[ keys to exit insert mode and return to command mode. The following commands invoke insert mode:

a

Append after cursor

A

Append at end-of-line

c

Begin change operation (must be followed by a movement command)

C

Change to end-of-line

i

Insert before cursor

I

Insert at beginning of line

o

Open a line below current line

O

Open a line above current line

r

Replace character under cursor

R

Begin overwriting text

s

Substitute a character

S

Substitute entire line

11.1.3 Syntax of vi Commands

In vi, commands have the following general form:

[n] operator [m] object

The basic editing operators are:

c

Begin a change

d

Begin a deletion

y

Begin a yank (or copy)

If the current line is the object of the operation, the operator is the same as the object: cc, dd, yy. Otherwise, the editing operators act on objects specified by cursor-movement commands or pattern-matching commands. n and m are the number of times the operation is performed or the number of objects the operation is performed on. If both n and m are specified, the effect is n x m.

An object can represent any of the following text blocks:

Word

Includes characters up to a space or punctuation mark. A capitalized object is a variant form that recognizes only blank spaces.

Sentence

Extends to ., !, or ? followed by two spaces.

Paragraph

Extends to next blank line or nroff/troff paragraph macro (defined by para= option).

Section

Extends to next nroff/troff section heading (defined by sect= option).

11.1.3.1 Examples
2cw

Change the next two words

d}

Delete up to next paragraph

d^

Delete back to beginning of line

5yy

Copy the next five lines into temporary buffer (for future pasting)

y]]

Copy up to the next section into temporary buffer (for future pasting)

11.1.4 Status-Line Commands

Most commands are not echoed on the screen as you input them. However, the status line at the bottom of the screen is used to echo input for the following commands:

/

Search forward for a pattern

?

Search backward for a pattern

:

Invoke an ex command

!

Pipe the text indicated by a subsequent movement command through the following shell command, and replace the text with the output of the shell command

Commands that are input on the status line must be entered by pressing the Return key. In addition, error messages and output from the Ctrl-G command are displayed on the status line.


11.2 vi Command-Line Options

The three most common ways of starting a vi session are:

vi  file

vi + n file

vi +/  pattern  file

You can open file for editing, optionally at line n or at the first line matching pattern. If no file is specified, vi opens with an empty buffer. The command-line options that can be used with vi are as follows (vim-only options are labeled):

+[num]

Start editing at line number num, or the last line of the file if num is omitted.

+/pattern

Start editing at the first line matching pattern. (Fails if nowrapscan is set in your .exrc startup file.)

-b

Edit the file in binary mode. {vim}

-c command

Run the given vi command upon startup. Only one -c option is permitted. ex commands can be invoked by prefixing them with a colon. An older form of this option, +command, is still supported.

--cmd command

Like -c, but execute the command before any resource files are read. {vim}

-d

Run in diff mode. Works like vimdiff. {vim}

-e

Run as ex (line editing rather than full-screen mode).

-h

Print help message, then exit.

-i file

Use the specified file instead of the default .viminfo to save or restore vim's state. {vim}

-l

Enter LISP mode for running LISP programs (not supported in all versions).

-m

Start the editor with the write option turned off so the user cannot write to files. {vim}

-n

Do not use a swap file; record changes in memory only. {vim}

--noplugin

Do not load any plug-ins. {vim}

-o[n]

Start vim with n open windows. The default is to open one window for each file. {vim}

-r [file]

Recovery mode; recover and resume editing on file after an aborted editor session or system crash. Without file, list files available for recovery.

-s, -s scriptfile

When running in ex mode (-e), suppress prompts or informative messages sent to the console. Otherwise, read and execute commands given in the specified scriptfile as if they were typed in from the keyboard. {vim}

-t tag

Edit the file containing tag and position the cursor at its definition. (See ctags in Chapter 3 for more information.)

-u file

Read configuration information from the specified resource file instead of default .vimrc resource files. If the file argument is NONE, vim will read no resource files, load no plug-ins, and run in compatible mode. If the argument is NORC, it will read no resource files but it will load plug-ins. {vim}

-v

Run in full-screen mode (default).

--version

Print version information, then exit.

-w rows

Set the window size so rows lines at a time are displayed; useful when editing over a slow dial-up line.

-x

Prompt for a key that will be used to try to encrypt or decrypt a file using crypt (not supported in all versions).

-y

Modeless vi; run vim in insert mode only, without a command mode. This is the same as invoking vim as evim. {vim}

-C

Same as -x, but assume the file is encrypted already (not supported in all versions). For vim this option starts the editor in vi-compatible mode.

-D

Debugging mode for use with scripts. {vim}

-L

List files that were saved due to an aborted editor session or system crash (not supported in all versions). For vim this option is the same as -r.

-M

Do not allow text in files to be modified. {vim}

-N

Run vim in a non-vi-compatible mode. {vim}

-O[n]

Start vim with n open windows arranged vertically on the screen. {vim}

-R

Edit files read-only.

-S commandfile

Source commands given in commandfile after loading any files for editing specified on the command line. Shorthand for the option -c source. {vim}

-T type

Set the terminal type. This value overrides the $TERM environment variable. {vim}

-V[n]

Verbose mode; print messages about what options are being set and what files are being read or written. You can set a level of verbosity to increase or decrease the number of messages received. The default value is 10 for high verbosity. {vim}

-W scriptfile

Write all typed commands from the current session to the specified scriptfile. The file created can be used with the -s command. {vim}

-Z

Start vim in restricted mode. Do not allow shell commands or suspension of the editor. {vim}


11.3 ex Command-Line Options

While most people know ex commands only by their use within vi, the editor also exists as a separate program and can be invoked from the shell (for instance, to edit files as part of a script). Within ex, you can enter the vi or visual command to start vi. Similarly, within vi, you can enter Q to quit the vi editor and enter ex.

If you invoke ex as a standalone editor, you can include the following options:

+[num]

Start editing at line number num, or the last line of the file if num is omitted.

+/pattern

Start editing at the first line matching pattern. (Fails if nowrapscan is set in your .exrc startup file.)

-c command

Run the given ex command upon startup. Only one -c option is permitted. An older form of this option, +command, is still supported.

-e

Run as a line editor rather than full-screen vi mode (default).

-l

Enter LISP mode for running LISP programs (not supported in all versions).

-r [file]

Recover and resume editing on file after an aborted editor session or system crash. Without file, list files available for recovery.

-s

Silent; do not display prompts. Useful when running a script. This behavior also can be set through the older - option.

-t tag

Edit the file containing tag and position the cursor at its definition (see ctags in Chapter 3 for more information).

-v

Run in full-screen mode (same as invoking vi).

-w rows

Set the window size so rows lines at a time are displayed; useful when editing by a slow dial-up line.

-x

Prompt for a key that will be used to try to encrypt or decrypt a file using crypt (not supported in all versions).

-C

Same as -x, but assume the file is encrypted already (not supported in all versions).

-L

List files that were saved due to an editor or system crash (not supported in all versions).

-R

Edit files read-only; do not allow changes to be saved.

You can exit ex in several ways:

:x

Exit (save changes and quit).

:q!

Quit without saving changes.

:vi

Enter the vi editor.


11.4 Movement Commands

Some versions of vi do not recognize extended keyboard keys (e.g., arrow keys, Page Up, Page Down, Home, Insert, and Delete); some do. All, however, recognize the keys in this section. Many users of vi prefer to use these keys, as it helps them keep their fingers on the home row of the keyboard. A number preceding a command repeats the movement. Movement commands are also objects for change, delete, and yank operations.

11.4.1 Character

Command | Action
h, j, k, l | Left, down, up, right ( [image] , [image] , [image] , [image] )
Spacebar | Right
Backspace | Left
Ctrl-H | Left

11.4.2 Text

Command | Action
w, b | Forward, backward by word (treating punctuation marks as words).
W, B | Forward, backward by word (recognizing only whitespace, not punctuation, as separators).
e | End of word (treating a punctuation mark as the end of a word).
E | End of word (recognizing only whitespace as the end of a word).
ge | End of previous word (treating a punctuation mark as the end of a word). {vim}
gE | End of previous word (recognizing only whitespace as the end of a word). {vim}
), ( | Beginning of next, current sentence.
}, { | Beginning of next, current paragraph.
]], [[ | Beginning of next, current section.
][, [ ] | End of next, current section. {vim}

11.4.3 Lines

Long lines in a file may show up on the screen as multiple lines. While most commands work on the lines as defined in the file, a few commands work on lines as they appear on the screen.

Command | Action
0, $ | First, last position of current line.
^, _ | First nonblank character of current line.
+, - | First character of next, previous line.
Return | First nonblank character of next line.
n| | Column n of current line.
g0, g$ | First, last position of screen line. {vim}
g^ | First nonblank character of screen line. {vim}
gm | Middle of screen line. {vim}
gk, gj | Move up, down one screen line. {vim}
H | Top line of screen.
M | Middle line of screen.
L | Last line of screen.
nH | n lines after top line of screen.
nL | n lines before last line of screen.

11.4.4 Screens

Command | Action
Ctrl-F, Ctrl-B | Scroll forward, backward one screen.
Ctrl-D, Ctrl-U | Scroll down, up one-half screen.
Ctrl-E, Ctrl-Y | Show one more line at bottom, top of window.
z Return | Reposition line with cursor to top of screen.
z. | Reposition line with cursor to middle of screen.
z- | Reposition line with cursor to bottom of screen.
Ctrl-L | Redraw screen (without scrolling).

11.4.5 Searches

Command | Action
/pattern | Search forward for pattern.
/ | Repeat previous search forward.
/pattern/+n | Go to line n after pattern.
?pattern | Search backward for pattern.
? | Repeat previous search backward.
?pattern?-n | Go to line n before pattern.
n | Repeat previous search.
N | Repeat previous search in opposite direction.
% | Find match of current parenthesis, brace, or bracket.
* | Search forward for word under cursor. Matches only exact words. {vim}
# | Search backward for word under cursor. Matches only exact words. {vim}
g* | Search backward for word under cursor. Matches the characters of this word when embedded in a longer word. {vim}
g# | Search backward for word under cursor. Matches the characters of this word when embedded in a longer word. {vim}
fx | Move forward to x on current line.
Fx | Move backward to x on current line.
tx | Move forward to just before x in current line.
Tx | Move backward to just after x in current line.
, | Reverse search direction of last f, F, t, or T.
; | Repeat last character search (f, F, t, or T).
:noh | Suspend search highlighting until next search. {vim}.

11.4.5.1 Line numbering

Command | Action
Ctrl-G | Display current filename and line number.
gg | Move to first line in file. {vim}
nG | Move to line number n.
G | Move to last line in file.
:n | Move to line number n.

11.4.5.2 Marking position

Command | Action
mx | Mark current position with character x.
`x | (backquote) Move cursor to mark x.
'x | (apostrophe) Move to start of line containing x.
`` | (backquotes) Return to previous mark (or location prior to search).
'' | (apostrophes) Like preceding, but return to start of line.
'" | (apostrophe quote) Move to position when last editing the file. {vim}
`[,`] | (backquote bracket) Move to beginning/end of previous text operation. {vim}
'[,'] | (apostrophe bracket) Like preceding, but return to start of line where operation occurred. {vim}
`. | (backquote period) Move to last change in file. {vim}
'. | (apostrophe period) Like preceding, but return to start of line. {vim}
:marks | List active marks. {vim}


11.5 Edit Commands

Recall that c, d, and y are the basic editing operators.

11.5.1 Inserting New Text

Command | Action
a | Append after cursor.
A | Append to end of line.
i | Insert before cursor.
I | Insert at first nonblank character of line.
gI | Insert at beginning of line. {vim}
o | Open a line below cursor.
O | Open a line above cursor.
Esc | Terminate insert mode.

The following commands work in insert mode.

Command | Action
Tab | Insert a tab.
Backspace | Delete previous character.
Ctrl-E | Insert character found just below cursor. {vim}
Ctrl-Y | Insert character found just above cursor. {vim}
Ctrl-H | Delete previous character (same as Backspace).
Delete | Delete current character.
Ctrl-W | Delete previous word. {vim}
Ctrl-A | Repeat last insertion. {vim}
Ctrl-I | Insert a tab.
Ctrl-N | Insert next completion of the pattern to the left of the cursor. {vim}
Ctrl-P | Insert previous completion of the pattern to the left of the cursor. {vim}
Ctrl-T | Shift line right to next shift width. {vim}
Ctrl-D | Shift line left to previous shift width. {vim}
Ctrl-U | Delete current line.
Ctrl-V | Insert next character verbatim.
Ctrl-[ | Terminate insert mode.

Some of the control characters listed in the previous table are set by stty. Your terminal settings may differ.

11.5.2 Changing and Deleting Text

The following table is not exhaustive, but illustrates the most common operations.

Command | Action
cw | Change through end of current word.
cc | Change line.
c$ | Change text from current position to end-of-line.
C | Same as c$.
dd | Delete current line.
d$ | Delete remainder of line.
D | Same as d$.
ndd | Delete n lines.
dw | Delete a word.
d} | Delete up to next paragraph.
d^ | Delete back to beginning of line.
d/pattern | Delete up to first occurrence of pattern.
dn | Delete up to next occurrence of pattern.
dfa | Delete up to and including a on current line.
dta | Delete up to (not including) a on current line.
dL | Delete up to last line on screen.
dG | Delete to end-of-file.
gqap | Reformat current paragraph to textwidth. {vim}
g~w | Switch case of word. {vim}
guw | Change word to lowercase. {vim}
gUw | Change word to uppercase. {vim}
p | Insert last deleted or yanked text after cursor.
gp | Same as p, but leave cursor at end of inserted text. {vim}
]p | Same as p, but match current indention. {vim}
[p | Same as P, but match current indention. {vim}
P | Insert last deleted or yanked text before cursor.
gP | Same as P, but leave cursor at end of inserted text. {vim}
rx | Replace character with x.
Rtext | Replace text beginning at cursor.
s | Substitute character.
ns | Substitute n characters.
S | Substitute entire line.
u | Undo last change.
Ctrl-R | Redo last change. {vim}
U | Restore current line.
x | Delete current character.
X | Delete back one character.
nX | Delete previous n characters.
. | Repeat last change.
~ | Reverse case.
& | Repeat last substitution.
Y | Copy (yank) current line to temporary buffer.
yy | Same as Y.
"xyy | Copy current line to buffer x.
ye | Copy text to end of word into temporary buffer.
yw | Same as ye.
y$ | Copy rest of line into temporary buffer.
"xdd | Delete current line into buffer x.
"Xdd | Delete current line and append to buffer x.
"xp | Put contents of buffer x.
J | Join previous line to current line.
gJ | Same as J, but without inserting a space. {vim}
:j! | Same as J.
Ctrl-A | Increment number under cursor. {vim}
Ctrl-X | Decrement number under cursor. {vim}


11.6 Saving and Exiting

Writing a file means saving the edits and updating the file's modification time.

Command | Action
ZZ | Quit vi, writing the file only if changes were made.
:x | Same as ZZ.
:wq | Write and quit file.
:w | Write file.
:w file | Save copy to file.
:n1,n2w file | Write lines n1 to n2 to new file.
:n1,n2w >> file | Append lines n1 to n2 to existing file.
:w! | Write file (overriding protection).
:w! file | Overwrite file with current buffer.
:w %.new | Write current buffer named file as file.new.
:q | Quit file.
:q! | Quit file (discarding edits).
Q | Quit vi and invoke ex.
:vi | Return to vi after Q command.
% | Current filename.
# | Alternate filename.


11.7 Accessing Multiple Files

Command | Action
:e file | Edit file; current file becomes the alternate file.
:e! | Restore last saved version of current file.
:e+ file | Begin editing at end of new file.
:e+ n file | Open new file at line n.
:e# | Open to previous position in alternate (previously edited) file.
:ta tag | Edit file containing tag at the location of the tag.
:n | Edit next file.
:n! | Force next file into buffer (don't save changes to current file).
:n files | Specify new list of files.
:args | Display multiple files to be edited.
:rew | Rewind list of multiple files to top.


11.8 Window Commands

The following table lists common commands for controlling windows in vim. See also the split, vsplit, and resize commands in Chapter 3. For brevity, control characters are marked in the following list by ^.

Command | Action
:new | Open a new window.
:new file | Open file in a new window.
:sp file | Split the current window.
:svfile | Same as :sp, but make new window read-only.
:snfile | Edit next file in new window.
:clo | Close current window.
:hid | Hide current window, unless it is the only visible window.
:on | Make current window the only visible one.
:res n | Resize window to n lines.
:wa | Write all changed buffers to file.
:qa | Close all buffers and exit.
^W s | Same as :sp.
^W n | Same as :new.
^W ^ | Open new window with alternate (previously edited) file.
^W c | Same as :clo.
^W o | Same as :only.
^W j, ^W k | Move cursor to next/previous window.
^W p | Move cursor to previous window.
^W h, ^W l | Move cursor to window on left/right.
^W t, ^W b | Move cursor to window on top/bottom of screen.
^W K, ^W B | Move current window to top/bottom of screen.
^W H, ^W L | Move current window to far left/right of screen.
^W r, ^W R | Rotate windows down/up.
^W +, ^W - | Increase/decrease current window size.
^W = | Make all windows same height.


11.9 Interacting with the Shell

Command | Action
:r file | Read in contents of file after cursor.
:r !command | Read in output from command after current line.
:nr !command | Like preceding, but place after line n (0 for top of file).
:!command | Run command, then return.
!object command | Send object, indicated by a movement command, as input to shell command command; replace object with command output.
:n1,n2! command | Send lines n1 through n2 to command; replace with output.
n!!command | Send n lines to command; replace with output.
!! | Repeat last system command.
!!command | Replace current line with output of command.
:sh | Create subshell; return to file with EOF.
Ctrl-Z | Suspend editor; resume with fg.
:so file | Read and execute ex commands from file.


11.10 Macros

Command | Action
:ab in out | Use in as abbreviation for out.
:unab in | Remove abbreviation for in.
:ab | List abbreviations.
:map c sequence | Map character c as sequence of commands.
:unmap c | Disable map for character c.
:map | List characters that are mapped.
:map! c sequence | Map character c to input mode sequence.
:unmap! c | Disable input mode map (you may need to quote the character with Ctrl-V).
:map! | List characters that are mapped to input mode.
qx | Record typed characters into register specified by letter x. If letter is uppercase, append to register.{vim}
q | Stop recording. {vim}
@x | Execute the register specified by letter x. {vim}

In vi, the following characters are unused in command mode and can be mapped as user-defined commands:

Letters

g K q V v

Control keys

^K ^O ^T ^W ^X

Symbols

_ * \ =

The = is used by vi if LISP mode is set. vim uses all of these characters, but you can create macros for function keys and multiple character commands. See :help :map for details. Other versions of vi may use some of these characters as well, so test them before using them.


11.11 Miscellaneous Commands

Command | Action
< | Shift line left to position indicated by following movement command.
> | Shift line right to position indicated by following movement command.
<< | Shift line left one shift width (default is 8 spaces).
>> | Shift line right one shift width (default is 8 spaces).
>} | Shift right to end of paragraph.
<% | Shift left until matching parenthesis, brace, bracket, etc. (Cursor must be on the matching symbol.)
= | Indent line in C-style, or using program specified in equalprg option. {vim}
K | Look up word under cursor in manpages (or program defined in keywordprg). {vim}
^[ | Abort command or end input mode.
^] | Perform a tag lookup on the text under the cursor.
^\ | Enter ex line-editing mode.
^^ | (Caret key with Ctrl key pressed) Return to previously edited file.


11.12 Alphabetical List of Keys in Command Mode

For brevity, control characters are marked by ^.

Command | Action
a | Append text after cursor.
A | Append text at end-of-line.
^A | Search for next occurrence of word under cursor. Increment number in vim when cursor is on a number.
b | Back up to beginning of word in current line.
B | Back up one word, treating punctuation marks as words.
^B | Scroll backward one window.
c | Change text up to target of next movement command.
C | Change to end of current line.
^C | End insert mode; interrupts a long operation.
d | Delete up to target of next movement command.
D | Delete to end of current line.
^D | Scroll down half-window; in insert mode, unindent to shiftwidth if autoindent is set (or when using vim).
e | Move to end of word.
E | Move to end of word, treating punctuation as part of word.
^E | Show one more line at bottom of window.
f | Find next character typed forward on current line.
F | Find next character typed backward on current line.
^F | Scroll forward one window.
g | Unused in vi. Begins many multiple-character commands in vim.
G | Go to specified line or end-of-file.
^G | Print information about file on status line.
h | Left arrow cursor key.
H | Move cursor to home position.
^H | Left arrow cursor key; Backspace key in insert mode.
i | Insert text before cursor.
I | Insert text before first nonblank character on line.
^I | Unused in command mode; in insert mode, same as Tab key.
j | Down arrow cursor key.
J | Join previous line to current line.
^J | Down arrow cursor key; in insert mode, move down a line.
k | Up arrow cursor key.
K | Unused in vi. Look up word using keywordprg in vim.
^K | Unused in vi. Insert multiple-keystroke character in vim.
l | Right arrow cursor key.
L | Move cursor to last position in window.
^L | Redraw screen.
m | Mark the current cursor position in register (a-z).
M | Move cursor to middle position in window.
^M | Move to beginning of next line.
n | Repeat the last search command.
N | Repeat the last search command in reverse direction.
^N | Down arrow cursor key.
o | Open line below current line.
O | Open line above current line.
^O | Unused in vi. Return to previous jump position in vim.
p | Put yanked or deleted text after or below cursor.
P | Put yanked or deleted text before or above cursor.
^P | Up arrow cursor key.
q | Unused in vi. Record keystrokes in vim.
Q | Quit vi and enter ex line-editing mode.
^Q | Unused in vi. Same as ^V in vim (On some terminals, resume data flow.)
r | Replace character at cursor with the next character you type.
R | Replace characters.
^R | Redraw the screen.
s | Change the character under the cursor to typed characters.
S | Change entire line.
^S | Unused. (On some terminals, stop data flow.)
t | Find next character typed forward on current line and position cursor before it.
T | Find next character typed backward on current line and position cursor after it.
^T | Unused in command mode for vi. Pop tag from tagstack in vim. In insert mode, move to next tab setting.
u | Undo the last change made. In vi, a second undo redoes an undone command. vim supports multiple levels of undo. To redo, use Ctrl-R.
U | Restore current line, discarding changes.
^U | Scroll the screen upward a half-window.
v | Unused in vi. Enter visual mode in vim.
V | Unused in vi. Enter linewise visual mode in vim.
^V | Unused in command mode for vi. Enter blockwise visual mode in vim. In insert mode, insert next character verbatim.
w | Move to beginning of next word.
W | Move to beginning of next word, treating punctuation marks as words.
^W | Unused in command mode in vi. Begins window commands in vim. In insert mode, back up to beginning of word.
x | Delete character under cursor.
X | Delete character before cursor.
^X | Unused in vi. Decrement number in vim when cursor is on a number. In insert mode in vim, begins several commands.
y | Yank or copy text up to target of following movement command into temporary buffer.
Y | Make copy of current line.
^Y | Show one more line at top of window.
z | Reposition line containing cursor. z must be followed by Return (reposition line to top of screen), . (reposition line to middle of screen), or - (reposition line to bottom of screen).
ZZ | Exit the editor, saving changes.


11.13 Syntax of ex Commands

To enter an ex command from vi, type:

:[address] command [options]

An initial : indicates an ex command. As you type the command, it is echoed on the status line. Enter the command by pressing Return. address is the line number or range of lines that are the object of command. options and addresses are described in the following sections. ex commands are described in the alphabetical summary.

11.13.1 Options

!

Indicates a variant command form, overriding the normal behavior.

count

The number of times the command is to be repeated. Unlike vi commands, the count comes after the command, not before it. Numbers preceding an ex command are considered to be part of the address. For example, 3d deletes line 3; d3 deletes 3 lines beginning with the current line.

file

The name of a file that is affected by the command. % stands for current file; # stands for previous file.

11.13.2 Addresses

If no address is given, the current line is the object of the command. If the address specifies a range of lines, the format is:

x,y

where x and y are the first and last addressed lines (x must precede y in the buffer). x and y may be line numbers or symbols. Using ; instead of , sets the current line to x before interpreting y.

11.13.3 Address Symbols

Symbol | Meaning
1,$ | All lines in the file
% | All lines; same as 1,$
x,y | Lines x through y
x;y | Lines x through y, with current line reset to x
0 | Top of file
. | Current line
n | Absolute line number n
$ | Last line
x-n | n lines before x
x+n | n lines after x
-[n] | One or n lines previous
+[n] | One or n lines ahead
'x | Line marked with x
'' | Previous mark
/pattern/ | Forward to line matching pattern
?pattern? | Backward to line matching pattern

See Chapter 9 for more information on using patterns.


11.14 Alphabetical Summary of ex Commands

ex commands can be entered by specifying any unique abbreviation. In this listing, the full name appears in the margin, and the shortest possible abbreviation is used in the syntax line. Examples are assumed to be typed from vi, so they include the : prompt.

abbrev
ab [string text]

Define string when typed to be translated into text. If string and text are not specified, list all current abbreviations.

Examples

Note: ^M appears when you type Ctrl-V followed by Return.

:ab ora O'Reilly & Associates, Inc.

:ab id Name:^MRank:^MPhone:
append
[address] a[!]

Append new text at specified address, or at present address if none is specified. Add a ! to switch the autoindent setting that will be used during input (e.g., if autoindent was enabled, ! disables it). Enter new text after entering the command. Terminate input of new text by entering a line consisting of just a period.

Example

a       Begin appending to current line.

Append this line

and this line too.

.        Terminate input of text to append.
args
ar

Print filename arguments (the list of files to edit). The current argument is shown in brackets ([ ]).

cd
cd dir

chdir dir

Change current directory within the editor to dir.

bdelete
[n] bd[!] [n]

Unload buffer n and remove it from the buffer list. Add a ! to force removal of an unsaved buffer. The buffer may also be specified by filename. If no buffer is specified, remove the current buffer. {vim}

buffer
[n] b[!] [n]

Begin editing buffer n in the buffer list. Add a ! to force a switch from an unsaved buffer. The buffer may also be specified by filename. If no buffer is specified, continue editing the current buffer. {vim}

buffers
buffers[!]

Print the listed members of the buffer list. Some buffers (e.g., deleted buffers) will not be listed. Add ! to show unlisted buffers. ls is another abbreviation for this command. {vim}

center
[address] ce [width]

Center line within the specified width. If width is not specified, use textwidth. {vim}

change
[address] c[!] text

Replace the specified lines with text. Add a ! to switch the autoindent setting during input of text. Terminate input by entering a line consisting of just a period.

close
clo[!]

Close current window unless it is the last window. If buffer in window is not open in another window, unload it from memory. This command will not close a buffer with unsaved changes, but you may add ! to hide it instead. {vim}

copy
[address] co destination

Copy the lines included in address to the specified destination address. The command t is the same as copy.

Example

1,10 co 50       Copy first 10 lines to just after line 50
delete
[address] d [buffer]

Delete the lines included in address. If buffer is specified, save or append the text to the named buffer.

Examples

/Part I/,/Part II/-1d       Delete to line above "Part II"

:/main/+d                    Delete line below "main"

:.,$d                        Delete from this line to last line
edit
e[!] [+n] [file]

Begin editing file. Add a ! to discard any changes to the current file. If no file is given, edit another copy of the current file. With the +n argument, begin editing on line n.

Examples

e file

:e#       Return to editing the previous file

:e!       Discard edits since last save
exusage
exu [command]

Print a brief usage message describing command, or a list of available commands if command is omitted. (In vim use the help command instead.)

file
f [filename]

Change the filename for the current buffer to filename. The next time the buffer is written, it will be written to file filename. When the name is changed, the buffer's notedited flag is set, to indicate you are not editing an existing file. If the new filename is the same as a file that already exists on the disk, you will need to use :w! to overwrite the existing file. When specifying a filename, the % character can be used to indicate the current filename. If no filename is specified, print the current name and status of the buffer.

Example

f %.new
fold
address fo

Fold the lines specified by address. A fold collapses several lines on the screen into one line, which can later be unfolded. It doesn't affect the text of the file. {vim}

foldclose
[address] foldc[!]

Close folds in specified address, or at present address if none is specified. Add a ! to close more than one level of folds. {vim}

foldopen
[address] foldo[!]

Open folds in specified address, or at present address if none is specified. Add a ! to open more than one level of folds. {vim}

global
[address] g[!]/pattern/[commands]

Execute commands on all lines that contain pattern or, if address is specified, on all lines within that range. If commands are not specified, print all such lines. If ! is used, execute commands on all lines that don't contain pattern. See v.

Examples

g/Unix/p                 Print all lines containing "Unix"

:g/Name:/s/tom/Tom/       Change "tom" to "Tom" on all lines

                         containing "Name:"
help
h

Print a brief help message. Information on particular commands can be obtained through the exusage and viusage commands. (In vim this command provides extensive information for all commands, and neither exusage nor viusage is used.)

hide
hid

Close current window unless it is the last window, but do not remove the buffer from memory. This is a safe command to use on an unsaved buffer. {vim}

insert
address i[!]

Insert new text at line before the specified address, or at present address if none is specified. Add a ! to switch the autoindent setting during input of text. Enter new text after entering the command. Terminate input of new text by entering a line consisting of just a period.

join
[address] j[!] [count]

Place the text in the specified address on one line, with whitespace adjusted to provide two blank characters after a period, no blank characters after a ), and one blank character otherwise. Add a ! to prevent whitespace adjustment.

Example

1,5j!       Join first five lines, preserving whitespace
jumps
ju

Print jump list used with Ctrl-I and Ctrl-O commands. The jump list is a record of most movement commands that skip over multiple lines. It records the position of the cursor before each jump. {vim}

k
[address] k char

Mark the given address with char. Return later to the line with 'char.

list
[address] l [count]

Print the specified lines so that tabs display as ^I, and the ends of lines display as $. The l command is a temporary version of :set list.

left
[address] le [count]

Left-align lines specified by address, or current line if no address is specified. Indent lines by count spaces. {vim}

map
map[!] [char commands]

Define a keyboard macro named char as the specified sequence of commands. char is usually a single character, or the sequence #n, representing a function key on the keyboard. Use a ! to create a macro for input mode. With no arguments, list the currently defined macros.

Examples

map K dwwP           Transpose two words

:map q :w^M:n^M       Write current file; go to next

:map! + ^[bi(^[ea)    Enclose previous word in parentheses
mark
[address] ma char

Mark the specified line with char, a single lowercase letter. Return later to the line with 'char. vim also uses uppercase and numeric characters for marks. Lowercase letters work the same as in vi. Uppercase letters are associated with filenames and can be used between multiple files. Numbered marks, however, are maintained in a special viminfo file and cannot be set using this command. Same as k.

marks
marks [chars]

Print list of marks specified by chars, or all current marks if no chars specified. {vim}

Example

marks abc     Print marks a, b and c.
mkexrc
mk[!] file

Create an .exrc file containing a set command for every ex option, set to defaults.

move
[address] m destination

Move the lines specified by address to the destination address.

Example

.,/Note/m /END/       Move text block after line containing "END"
new
[count]new

Create a new window count lines high with an empty buffer. {vim}

next
n[!] [[+command] filelist]

Edit the next file from the command-line argument list. Use args to list these files. If filelist is provided, replace the current argument list with filelist and begin editing on the first file; if command is given (containing no spaces), execute command after editing the first such file. Add a ! to discard any changes to the current file.

Example

n chap*       Start editing all "chapter" files
nohlsearch
noh

Temporarily stop highlighting all matches to a search when using the hlsearch option. Highlighting is resumed with the next search. {vim}

number
[address] nu [count]

Print each line specified by address, preceded by its buffer line number. Use # as an alternate abbreviation for number. count specifies the number of lines to show, starting with address.

open
[address] o [/pattern/]

Enter vi's open mode at the lines specified by address or at the lines matching pattern. Enter and exit open mode with Q. Open mode lets you use the regular vi commands, but only one line at a time. May be useful on slow dial-up lines.

preserve
pre

Save the current editor buffer as though the system had crashed.

previous
prev[!]

Edit the previous file from the command-line argument list.

print
[address] p [count]

[address] P [count]

Print the lines specified by address. count specifies the number of lines to print, starting with address. Add a ! to discard any changes to the current file.

Example

100;+5p       Show line 100 and the next 5 lines
put
[address] pu [char]

Restore the lines that were previously deleted or yanked from named buffer char, and put them after the line specified by address. If char is not specified, restore the last deleted or yanked text.

qall
qa[!]

Close all windows and terminate current editing session. Use ! to discard changes made since the last save. {vim}

quit
q[!]

Terminate current editing session. Use ! to discard changes made since the last save. If the editing session includes additional files in the argument list that were never accessed, quit by typing q! or by typing q twice. (In vim, if multiple windows are open, this command will close only the current window; use qall to quit multiple windows.)

read
[address] r file

Copy in the text from file on the line below the specified address. If file is not specified, the current filename is used.

Example

0r $HOME/data       Read file in at top of current file
read
[address] r !command

Read the output of Linux command into the text after the line specified by address.

Example

$r !cal       Place a calendar at end-of-file
recover
rec [file]

Recover file from system save area.

redo
red

Restore last undone change. Same as Ctrl-R. {vim}

resize
res [[+|-]n]

Resize current window to be n lines high. If + or - is specified, increase or decrease the current window height by n lines. {vim}

rewind
rew[!]

Rewind argument list and begin editing the first file in the list. The ! flag rewinds, discarding any changes to the current file that haven't been saved.

right
[address] le [width]

Right-align lines specified by address, or current line if no address is specified, to column width. Use textwidth option if no width is specified. {vim}

sbuffer
[n] sb [n]

Split the current window and begin editing buffer n from the buffer list in the new window. The buffer to be edited may also be specified by filename. If no buffer is specified, open the current buffer in the new window. {vim}

sbnext
[count] sbn [count]

Split the current window and begin editing the count next buffer from the buffer list. If no count is specified, edit the next buffer in the buffer list. {vim}

snext
[count] sn [[+n] filelist]

Split the current window and begin editing the next file from the command-line argument list. If count is provided, edit the count next file. If filelist is provided, replace the current argument list with filelist and begin editing the first file. With the +n argument, begin editing on line n. Alternately, n may be a pattern of the form /pattern. {vim}

split
[count] sp [+n] [filename]

Split the current window and load filename in the new window, or the same buffer in both windows if no file is specified. Make the new window count lines high, or if count is not specified, split the window into equal parts. With the +n argument, begin editing on line n. n may also be a pattern of the form /pattern. {vim}

sprevious
[count] spr [+n]

Split the current window and begin editing the previous file from the command-line argument list in the new window. If count is specified, edit the count previous file. With the +n argument, begin editing on line n. n may also be a pattern of the form /pattern. {vim}

script
sc[!] [file]

Create a new shell in a buffer that can be saved, optionally specifying file where the buffer can be saved. Can be used only in vi.

set
se parameter1 parameter2 ...

Set a value to an option with each parameter, or if no parameter is supplied, print all options that have been changed from their defaults. For Boolean-valued options, each parameter can be phrased as option or nooption; other options can be assigned with the syntax option=value. Specify all to list current settings.

Examples

set nows wm=10

:set all
shell
sh

Create a new shell. Resume editing when the shell is terminated.

source
so file

Read and execute ex commands from file.

Example

so $HOME/.exrc
stop
st

Suspend the editing session. Same as Ctrl-Z. Use fg to resume session.

substitute
[address] s [/pattern/replacement/] [options] [count]

Replace each instance of pattern on the specified lines with replacement. If pattern and replacement are omitted, repeat last substitution. count specifies the number of lines on which to substitute, starting with address. When preceded by the global (g) or v command, this command can be specified with a blank pattern, in which case the pattern from the g or v command is used. For more examples, see Chapter 9.

Options

c

Prompt for confirmation before each change.

g

Substitute all instances of pattern on each line.

p

Print the last line on which a substitution was made.

Examples

1,10s/yes/no/g                 Substitute on first 10 lines

:%s/[Hh]ello/Hi/gc              Confirm global substitutions

:s/Fortran/\U&/ 3               Uppercase first instance of

                                   "Fortran" on next three lines

:g/^[0-9][0-9]*/s//Line &:/    For every line beginning with one or

                               more digits, add the "Line" and a colon
suspend
su

Suspend the editing session. Same as Ctrl-Z. Use fg to resume session.

sview
[count] sv [+n] [filename

Same as the split command, but set the readonly option for the new buffer. {vim}

t
[address] t destination

Copy the lines included in address to the specified destination. t is an alias for copy.

Example

%t$       Copy the file and add it to the end
tag
[address] ta[!] tag

Switch the editing session to the file containing tag.

Example

Run ctags, then switch to the file containing myfunction:

:!ctags *.c

:tag  myfunction
tags
tags

Print list of tags in the tag stack. {vim}

unabbreviate
una word

Remove word from the list of abbreviations.

undo
u

Reverse the changes made by the last editing command. In vi the undo command will undo itself, redoing what you undid. vim supports multiple levels of undo. Use redo to redo an undone change in vim.

unhide
[count] unh

Split screen to show one window for each active buffer in the buffer list. If specified, limit the number of windows to count. {vim}

unmap
unm[!] char

Remove char from the list of keyboard macros. Use ! to remove a macro for input mode.

v
[address] v/pattern/[commands]

Execute commands on all lines not containing pattern. If commands are not specified, print all such lines. v is equivalent to g!. See global.

Example

v/#include/d       Delete all lines except "#include" lines
version
ve

Print the editor's current version number.

vi
vi [+n] file

Begin editing file, optionally at line n. Can be used only in vi.

view
vie[[+n] filename]

Same as edit, but set file to readonly. When executed in ex mode, return to normal or visual mode. {vim}

visual
[address] vi [type] [count]

Enter visual mode (vi) at the line specified by address. Exit with Q. type can be one of -, ^, or .. (See the z command.) count specifies an initial window size.

viusage
viu [key]

Print a brief usage message describing the operation of key, or a list of defined keys if key is omitted. (In vim use the help command instead.)

vsplit
[count] vs [+n] [filename]

Same as the split command, but split the screen vertically. The count argument can be used to specify a width for the new window. {vim}

wall
wa[!]

Write all changed buffers with filenames. Add ! to force writing of any buffers marked readonly. {vim}

wnext
[count] wn[!] [[+n] filename]

Write current buffer and open next file in argument list, or the count next file if specified. If filename is specified, edit it next. With the +n argument, begin editing on line n. n may also be a pattern of the form /pattern. {vim}

wq
wq[!]

Write and quit the file in one command. The ! flag forces the editor to write over any current contents of file.

wqall
wqa[!]

Write all changed buffers and quit the editor. Add ! to force writing of any buffers marked readonly. xall is another alias for this command. {vim}

write
[address] w[!] [[>>] file]

Write lines specified by address to file, or write full contents of buffer if address is not specified. If file is also omitted, save the contents of the buffer to the current filename. If >>file is used, write contents to the end of an existing file. The ! flag forces the editor to write over any current contents of file.

write
[address] w !command

Write lines specified by address to command.

Examples

1,10w name_list        Copy first 10 lines to name_list

:50w >> name_list       Now append line 50
X
X

Prompt for an encryption key. This can be preferable to :set key as typing the key is not echoed to the console. To remove an encryption key, just reset the key option to an empty value. {vim}

xit
x

Write the file if it was changed since the last write, then quit.

yank
[address] ya [char] [count]

Place lines specified by address in named buffer char. If no char is given, place lines in general buffer. count specifies the number of lines to yank, starting with address.

Example

101,200 ya a
z
[address] z [type] [count]

Print a window of text, with the line specified by address at the top. count specifies the number of lines to be displayed.

Type

+

Place specified line at top of window (the default).

-

Place specified line at bottom of window.

.

Place specified line in center of window.

^

Move up one window.

=

Place specified line in center of window, and leave as the current line.

!
[address] !command

Execute Linux command in a shell. If address is specified, apply the lines contained in address as standard input to command, and replace the lines with the output.

Examples

!ls                 List files in the current directory

:11,20!sort -f       Sort lines 11-20 of current file
=
[address] =

Print the line number of the next line matching address. If no address is given, print the number of the last line.

< >
[address]<[count]

[address]>[count]

Shift lines specified by address either left (<) or right (>). Only blanks and tabs are removed in a left shift. count specifies the number of lines to shift, starting with address.

address
address

Print the line specified in address.

Return
Return

Print the next line in the file.

@
[address] @ [char]

Execute contents of register specified by char. If address is given, move cursor to the specified address first. Both star and * are aliases for this command. {vim}

@@
[address] @

Repeat the last @ command. If address is given, move cursor to the specified address first. {vim}

&
& [options] [count]

Repeat the previous substitution (s) command. count specifies the number of lines on which to substitute, starting with address.

Examples

s/Overdue/Paid/      Substitute once on current line

:g/Status/&           Redo substitution on all "Status" lines
~
[address] ~ [count]

Replace the previous regular expression with the previous replacement pattern from a substitute (s) command.


11.15 vi Configuration

This section describes the following:

  • The :set command

  • Options available with :set

  • Sample ~/.exrc file

11.15.1 The :set Command

The :set command lets you specify options that change characteristics of your editing environment. Options may be put in the ~/.exrc file or set during a vi session.

The colon should not be typed if the command is put in ~/.exrc.

Command | Action
:set x | Enable option x.
:set no x | Disable option x.
:set x=val | Give value to option x.
:set | Show changed options.
:set all | Show all options.
:set x? | Show value of option x.

11.15.2 Options Used by :set

The following table describes the options to :set. The first column includes the optional abbreviation, if there is one, and uses an equals sign to show that the option takes a value. The second column gives the default, and the third column describes the behavior of the enabled option.

Option | Default | Description
autoindent (ai) | noai | In insert mode, indent each line to the same level as the line above or below.
autoprint (ap) | ap | Display changes after each editor command. (For global replacement, display last replacement.)
autowrite (aw) | noaw | Automatically write (save) file if changed, before opening another file with :n or before giving a Linux command with :!.
background (bg) |  | Describe the background so the editor can choose appropriate highlighting colors. Default value of dark or light depends on the environment in which the editor is invoked. {vim}
backup (bk) | nobackup | Create a backup file when overwriting an existing file. {vim}
backupdir= (bdir) | .,~/tmp/,~/ | Name directories in which to store backup files if possible. The list of directories is comma-separated and in order of preference. {vim}
backupext= (bex) | ~ | String to append to filenames for backup files. {vim}
beautify (bf) | nobf | Ignore all control characters during input (except tab, newline, or formfeed).
cindent (cin) | nocindent | Insert indents in appropriate C format. {vim}
compatible (cp) | cp | Make vim behave more like vi. Default is nocp when a ~/.vimrc file is found. {vim}
directory= (dir) | /tmp | Name the directory in which ex stores buffer files. (Directory must be writable.)
edcompatible | noed-compatible | Use ed-like features on substitute commands.
equalprg= (ep) |  | Use the specified program for the = command. When the option is blank (the default), the key invokes the internal C indention function or the value of the indentexpr option. {vim}
errorbells (eb) | errorbells | Sound bell when an error occurs.
exrc (ex) | noexrc | Allow the execution of ~/.exrc files that reside outside the user's home directory.
formatprg= (fp) |  | The gq command will invoke the named external program to format text. It will call internal formatting functions when this option is blank (the default). {vim}
gdefault (gd) | nogdefault | Set the g flag on for substitutions by default. {vim}
hardtabs= (ht) | 8 | Define boundaries for terminal hardware tabs.
hidden (hid) | nohidden | Hide buffers rather than unload them when they are abandoned. {vim}
hlsearch (hls) | hlsearch | Highlight all matches of most recent search.
history= (hi) | 20 | Number of ex commands to store in the history table. {vim}
ignorecase (ic) | noic | Disregard case during a search.
incsearch (is) | noincsearch | Highlight matches to a search pattern as it is typed. {vim}
lisp | nolisp | Insert indents in appropriate LISP format. ( ), { }, [[, and ]] are modified to have meaning for LISP.
list | nolist | Print tabs as ^I; mark ends of lines with $. (Use list to tell if tabs or spaces are at the end of a line.)
magic | magic | Wildcard characters . (dot), * (asterisk), and [ ] (brackets) have special meaning in patterns.
mesg | mesg | Permit system messages to display on terminal while editing in vi.
mousehide (mh) | mousehide | When characters are typed, hide the mouse pointer. {vim}
number (nu) | nonu | Display line numbers on left of screen during editing session.
paste | nopaste | Change the defaults of various options to make pasting text into a terminal window work better. All options are returned to their original value when the paste option is reset. {vim}
redraw (re) | noredraw | Terminal redraws screen whenever edits are made (in other words, insert mode pushes over existing characters, and deleted lines immediately close up). Default depends on line speed and terminal type. noredraw is useful at slow speeds on a dumb terminal: deleted lines show up as @, and inserted text appears to overwrite existing text until you press Esc.
remap | remap | Allow nested map sequences.
report= | 5 | Display a message on the prompt line whenever you make an edit that affects at least a certain number of lines. For example, 6dd reports the message "6 lines deleted."
ruler (ru) | ruler | Show line and column numbers for the current cursor position. {vim}
scroll= | <1/2 window> | Amount of screen to scroll.
sections= (sect) | SHNHH HUnhsh | Define section delimiters for [[ ]] movement. The pairs of characters in the value are the names of nroff/troff macros that begin sections.
shell= (sh) | /bin/sh | Pathname of shell used for shell escape (:!) and shell command (:sh). Default value is derived from SHELL variable.
shiftwidth= (sw) | 8 | Define number of spaces used by the indent commands (^T, ^D, >>, and <<).
showmatch (sm) | nosm | In vi, when ) or } is entered, cursor moves briefly to matching ( or {. (If the match is not on the screen, rings the error message bell.) Very useful for programming.
showmode | noshowmode | In insert mode, displays a message on the prompt line indicating the type of insert you are making, such as "Open Mode" or "Append Mode."
slowopen (slow) |  | Hold off display during insert. Default depends on line speed and terminal type.
smartcase (scs) | nosmartcase | Override the ignorecase option when a search pattern contains uppercase characters. {vim}
tabstop= (ts) | 8 | Define number of spaces that a tab indents during editing session. (Printer still uses system tab of 8.)
taglength= (tl) | 0 | Define number of characters that are significant for tags. Default (0) means that all characters are significant.
tags= | tags /usr/lib/tags | Define pathname of files containing tags (see the ctags command in Chapter 3). By default, the system looks for files tags (in the current directory) and /usr/lib/tags.
term= |  | Set terminal type.
terse | noterse | Display shorter error messages.
timeout (to) | timeout | Keyboard maps timeout after 1 second.
ttytype= |  | Set terminal type. Default is inherited from TERM environment variable.
undolevels= (ul) | 1000 | Number of changes that can be undone. {vim}
warn | warn | Display the message "No write since last change."
window= (w) |  | Show a certain number of lines of the file on the screen. Default depends on line speed and terminal type.
wrapmargin= (wm) | 0 | Define right margin. If greater than 0, automatically insert carriage returns to break lines.
wrapscan (ws) | ws | Searches wrap around either end of file.
writeany (wa) | nowa | Allow saving to any file.
writebackup (wb) | wb | Back up files before attempting to overwrite them. Remove the backup when the file has been sucessfully written.

11.15.3 Sample ~/.exrc File

The following lines of code are an example of a customized .exrc file:

set nowrapscan wrapmargin=7

set sections=SeAhBhChDh nomesg

map q :w^M:n^M

map v dwElp

ab ORA O'Reilly & Associates, Inc.


Chapter 12. The sed Editor

sed is a noninteractive (stream-oriented) editor that interprets and performs the actions in a script. sed is said to be stream-oriented because, as with many Unix programs, input flows through the program and is directed to standard output. For example, sort is stream-oriented; vi is not. sed's input typically comes from a file but can be directed from the keyboard. Output goes to the screen by default but can be captured in a file instead.

Typical uses of sed include:

  • Editing one or more files automatically

  • Simplifying repetitive edits to multiple files

  • Writing conversion programs

sed operates as follows:

  • Each line of input is copied into a pattern space.

  • All editing commands in a sed script are applied in order to each line of input.

  • Editing commands are applied to all lines (globally) unless line addressing restricts the lines affected.

  • If a command changes the input, subsequent commands are applied to the changed line, not to the original input line.

  • The original input file is unchanged because the editing commands modify a copy of the original input line. The copy is sent to standard output (but can be redirected to a file).

For more information on sed, see sed & awk (O'Reilly).


12.1 Command-Line Syntax

The syntax for invoking sed has two forms:

sed  [options ] 'command' file(s)

sed  [options ] -f  scriptfile file(s)

The first form allows you to specify an editing command, surrounded by single quotes, on the command line. The second form allows you to specify a scriptfile, which is a file containing sed commands. If no files are specified, sed reads from standard input.

The following options are recognized:

-e cmd, --expression=cmd

Next argument is an editing command; not needed unless specifying two or more editing commands.

-f scriptfile, --file=scriptfile

Next argument is a file containing editing commands.

-n, --silent, --quiet

Suppress the default output; sed displays only those lines specified with the p command or with the p flag of the s command.

-V, --version

Display version number.

-h, --help

Display brief help message with command-line options.


12.2 Syntax of sed Commands

sed commands have the general form:

[address [,address ]][! ]command  [arguments ]

sed commands consist of addresses and editing commands. commands consist of a single letter or symbol; they are described later, alphabetically and by group. Some commands accept or expect arguments. Examples of arguments include the label supplied to b or t, the filename supplied to r or w, and the substitution flags for s. addresses are described in the next section.

12.2.1 Pattern Addressing

A sed command can specify zero, one, or two addresses. An address can be a line number, an increment given as a starting line number and a step amount separated by a tilde (~), the symbol $ (for last line), or a regular expression enclosed in slashes (/pattern/). Regular expressions are described in Chapter 9. Additionally, \n can be used to match any newline in the pattern space (resulting from the N command) but not the newline at the end of the pattern space.

If the command specifies | Then the command is applied to
No address | Each input line.
One address | Any line matching the address. Some commands (a, i, r, q, and =) accept only one address.
Two comma-separated addresses | First matching line and all succeeding lines up to and including a line matching the second address.
An address followed by ! | All lines that do not match the address.

12.2.1.1 Examples
s/xx/yy/g                Substitute on all lines (all occurrences)

/BSD/d                   Delete lines containing BSD

/^BEGIN/,/^END/p         Print  all lines between lines that begin with

                        BEGIN and END, inclusive

/SAVE/!d                 Delete any line that doesn't contain SAVE

/BEGIN/,/END/!s/xx/yy/g  Substitute on all lines, except between BEGIN and END

1~2 p                    Print all odd numbered lines

2~3 d                    Delete every third line beginning with the second.

Braces ({ }) are used in sed to nest one address inside another or to apply multiple commands at the same address:

[/address/[,/address/]]{

command1

command2

}

The opening curly brace must end a line, and the closing curly brace must be on a line by itself. Be sure there are no blank spaces after the braces.


12.3 Group Summary of sed Commands

In the following tables, the sed commands are grouped by function and are described tersely. Full descriptions, including syntax and examples, can be found afterward in the alphabetical summary.

12.3.1 Basic Editing

Command | Action
a\ | Append text after a line.
c\ | Replace text (usually a text block).
i\ | Insert text before a line.
d | Delete lines.
s | Make substitutions.
y | Translate characters (like tr in Chapter 3).

12.3.2 Line Information

Command | Action
= | Display line number of a line.
l | Display control characters in ASCII.
p | Display the line.

12.3.3 Input/Output Processing

Command | Action
n | Skip current line and go to line below.
r | Read another file's contents into the input.
w | Write input lines to another file.
q | Quit the sed script (no further output).

12.3.4 Yanking and Putting

Command | Action
h | Copy pattern space into hold space; wipe out what's there.
H | Copy pattern space into hold space; append to what's there.
g | Get the hold space back; wipe out the pattern space.
G | Get the hold space back; append to the pattern space.
x | Exchange contents of hold space and pattern space.

12.3.5 Branching Commands

Command | Action
b | Branch to label or to end of script.
t | Same as b, but branch only after substitution.
:label | Label branched to by t or b.

12.3.6 Multiline Input Processing

Command | Action
N | Read another line of input (creates embedded newline).
D | Delete up to the embedded newline.
P | Print up to the embedded newline.


12.4 Alphabetical Summary of sed Commands

#
#

Begin a comment in a sed script. Valid only as the first character of the first line. (Some versions of sed, including the GNU version on Linux, allow comments anywhere, but it is better not to rely on this.) If the first line of the script is #n, sed behaves as if -n had been specified.

:
:label

Label a line in the script for the transfer of control by b or t. label may contain up to seven characters.

=
[/pattern/]=

Write to standard output the line number of each line containing pattern.

a
[address]a\

text

Append text following each line matched by address. If text goes over more than one line, newlines must be "escaped" by preceding them with a backslash. The text will be terminated by the first newline that is not escaped in this way. The text is not available in the pattern space, and subsequent commands cannot be applied to it. The results of this command are sent to standard output when the list of editing commands is finished, regardless of what happens to the current line in the pattern space.

Example

$a\

This goes after the last line in the file\

(marked by $). This text is escaped at the\

end of each line, except for the last one.
b
[address1[,address2]]b[label]

Transfer control unconditionally to :label elsewhere in script. That is, the command following the label is the next command applied to the current line. If no label is specified, control falls through to the end of the script, so no more commands are applied to the current line.

Example

Ignore lines between those that begin with .TS and .TE; resume script after .TE:

/^\.TS/,/^\.TE/b
c
[address1[,address2]]c\text

Replace the lines selected by the address with text. When a range of lines is specified, all lines as a group are replaced by a single copy of text. The newline following each line of text must be escaped by a backslash, except the last line. The contents of the pattern space are in effect deleted, and no subsequent editing commands can be applied.

Example

Replace first 100 lines in a file:

1,100c\

\

<First 100 names to be supplied>
d
[address1[,address2]]d

Delete the addressed line (or lines) from the pattern space. Thus, the line is not passed to standard output. A new line of input is read, and editing resumes with the first command in the script.

Example

Delete all blank lines (those whose first character is a line ending):

/^$/d
D
[address1[,address2]]D

Delete first part (up to embedded newline) of multiline pattern space created by the N command, and resume editing with first command in script. If this command empties the pattern space, then a new line of input is read, as if d had been executed.

Example

Strip multiple blank lines, leaving only one:

/^$/{

N

/^\n$/D

}
g
[address1[,address2]]g

Paste the contents of the hold space (see h and H) back into the pattern space, wiping out the previous contents of the pattern space. The example shows a simple way to copy lines.

Example

This script collects all lines containing the word Item: and copies them to a place marker later in the file. The place marker is overwritten.

/Item:/H

/<Replace this line with the item list>/g
G
[address1[,address2]]G

Same as g, except the hold space is pasted below the address instead of overwriting it. The example shows a simple way to cut and paste lines.

Example

This script collects all lines containing the word Item: and moves them after a place marker later in the file. The original Item: lines are deleted.

/Item:/{

H

d

}

/Summary of items:/G
h
[address1[,address2]]h

Copy the pattern space into the hold space, a special temporary buffer. The previous contents of the hold space are obliterated. You can use h to save a line before editing it.

Example

# Edit a line; print the change; replay the original

/Linux/{

h

s/.* Linux \(.*\) .*/\1:/

p

x

}

Sample input:

This describes the Linux ls command.

This describes the Linux cp command.

Sample output:

ls:

This describes the Linux ls command.

cp:

This describes the Linux cp command.
H
[address1[,address2]]H

Append the contents of the pattern space (preceded by a newline) to the contents of the hold space. Even if the hold space is empty, H still appends a newline. H is like an incremental copy. See examples under g and G.

i
[address1]i\

text

Insert text before each line matched by address. (See a for details on text.)

Example

/Item 1/i\

The five items are listed below:
l
[address1[,address2]]l

List the contents of the pattern space, showing nonprinting characters as ASCII codes. Long lines are wrapped.

n
[address1[,address2]]n

Read next line of input into pattern space. The current line is sent to standard output, and the next line becomes the current line. Control passes to the command following n instead of resuming at the top of the script.

Example

In the ms macros, a section header occurs on the line below an .NH macro. To print all lines of header text, invoke this script with sed -n:

/^\.NH/{

n

p

}
N
[address1[,address2]]N

Append next input line to contents of pattern space; the two lines are separated by an embedded newline. (This command is designed to allow pattern matches across two lines.) Using \n to match the embedded newline, you can match patterns across multiple lines. See example at D.

Examples

Like previous example, but print .NH line as well as header title:

/^\.NH/{

N

p

}

Join two lines (replace newline with space):

/^\.NH/{

N

s/\n/ /

p

}
p
[address1[,address2]]p

Print the addressed lines. Unless the -n command-line option is used, this command causes duplicate lines to be output. Also, it is typically used before commands that change flow control (d, N, b) and that might prevent the current line from being output. See examples at h, n, and N.

P
[address1[,address2]]P

Print first part (up to embedded newline) of multiline pattern created by N command. Same as p if N has not been applied to a line.

q
[address]q

Quit when address is encountered. The addressed line is first written to output (if default output is not suppressed), along with any text appended to it by previous a or r commands.

Examples

Delete everything after the addressed line:

/Garbled text follows:/q

Print only the first 50 lines of a file:

50q
r
[address]r file

Read contents of file and append after the contents of the pattern space. One space must be put between the r and the filename.

Example

/The list of items follows:/r item_file
s
[address1[,address2]]s/pattern/replacement/[flags]

Substitute replacement for pattern on each addressed line. If pattern addresses are used, the pattern // represents the last pattern address specified. The following flags can be specified:

n

Replace nth instance of /pattern/ on each addressed line. n is any number in the range 1 to 512; the default is 1.

g

Replace all instances of /pattern/ on each addressed line, not just the first instance.

I

Case insensitive match. This flag is available only on GNU versions of sed.

p

Print the line if a successful substitution is done. If several successful substitutions are done, multiple copies of the line will be printed.

w file

Write the line to a file if a replacement was done.

Examples

Here are some short, commented scripts:

# Change third and fourth quote to ( and ):

/function/{

s/"/(/3

s/"/)/4

}

# Remove all quotes on a given line:

/Title/s/"//g

# Remove first colon or all quotes; print resulting lines:

s/://p

s/"//gp

# Change first "if" but leave "ifdef" alone:

/ifdef/!s/if/   if/
t
[address1[,address2]]t [label]

Test if any substitutions have been made on addressed lines and, if so, branch to line marked by :label. (See b and :.) If label is not specified, control falls through to bottom of script. The t command is like a case statement in the C programming language or the shell programming languages. You test each case; when it's true, you exit the construct.

Example

Suppose you want to fill empty fields of a database. You have this:

ID: 1   Name: greg   Rate: 45

ID: 2   Name: dale

ID: 3

and you want this:

ID: 1   Name: greg   Rate: 45   Phone: ??

ID: 2   Name: dale   Rate: ??   Phone: ??

ID: 3   Name: ????   Rate: ??   Phone: ??

You need to test the number of fields already there. Here's the script (fields are tab-separated):

/ID/{

s/ID: .* Name: .* Rate: .*/&   Phone: ??/p

t

s/ID: .* Name: .*/&   Rate: ??   Phone: ??/p

t

s/ID: .*/&   Name: ??     Rate: ??   Phone: ??/p

}
w
[address1[,address2]]w file

Append contents of pattern space to file. This action occurs when the command is encountered, rather than when the pattern space is output. Exactly one space must separate the w and the filename. This command will create the file if it does not exist; if the file does exist, its contents will be overwritten each time the script is executed. Multiple write commands that direct output to the same file append to the end of the file.

Example

# Store tbl and eqn blocks in a file:

/^\.TS/,/^\.TE/w troff_stuff

/^\.EQ/,/^\.EN/w troff_stuff
x
[address1[,address2]]x

Exchange contents of the pattern space with contents of the hold space. See h for an example.

y
[address1[,address2]]y/abc/xyz/

Translate characters. Change every instance of a to x, b to y, c to z, etc.

Example

# Change item 1, 2, 3 to Item A, B, C ...

/^item [1-9]/y/123456789/ABCDEFGHI/

f


Chapter 13. The gawk Scripting Language

gawk is the GNU version of awk, a powerful pattern-matching program for processing text files that may be composed of fixed- or variable-length records separated by some delineator (by default, a newline character). gawk may be used from the command line or in gawk scripts. You should normally be able to invoke this utility using either awk or gawk on the shell command line.

With gawk, you can:

  • Conveniently process a text file as though it were made up of records and fields in a textual database.

  • Use variables to change those records and fields.

  • Execute shell commands from a script.

  • Perform arithmetic and string operations.

  • Use programming constructs such as loops and conditionals.

  • Define your own functions.

  • Process the result of shell commands.

  • Produce formatted reports.

For more information on gawk, see sed & awk (O'Reilly) or Effective gawk Programming (O'Reilly).


13.1 Command-Line Syntax

gawk's syntax has two forms:

gawk [options] 'script' var=value file(s)

gawk [options] -f scriptfile var=value file(s)

You can specify a script directly on the command line, or you can store a script in a scriptfile and specify it with -f. Multiple -f options are allowed; awk concatenates the files. This feature is useful for including libraries.

gawk operates on one or more input files. If none are specified (or if - is specified), gawk reads from standard input.

Variables can be assigned a value on the command line. The value assigned to a variable can be a literal, a shell variable ($name), or a command substitution (`cmd`), but the value is available only after a line of input is read (i.e., after the BEGIN statement).

For example, to print the first three (colon-separated) fields of the password file, use -F to set the field separator to a colon:

gawk -F : '{print $1; print $2; print $3}' /etc/passwd

Numerous examples are shown later in Section 13.2.

13.1.1 Options

All options exist in both traditional POSIX (one-letter) format and GNU-style (long) format. Some recognized options are:

--

Treat all subsequent text as commands or filenames, not options.

-f scriptfile, --file=scriptfile

Read gawk commands from scriptfile instead of command line.

-v var=value, --assign=var=value

Assign a value to variable var. This allows assignment before the script begins execution.

-F c, --field-separator=c

Set the field separator to character c. This is the same as setting the variable FS. c may be a regular expression. Each input line, or record, is divided into fields by whitespace (blanks or tabs) or by some other user-definable record separator. Fields are referred to by the variables $1, $2,..., $n. $0 refers to the entire record.

-W option

All -W options are specific to gawk, as opposed to awk. An alternate syntax is --option (i.e., --compat). option may be one of:

compat, traditional

Behave exactly like traditional (non-GNU) awk.

copyleft, copyright

Print copyleft notice and exit.

dump-variables[=file]

Print the name, type, and value of all global variables to the specified file, or to the file awkvars.out in the current directory if no file is specified.

help, usage

Print syntax and list of options, then exit.

lint[=fatal]

Warn about commands that might not port to other versions of awk or that gawk considers problematic. When fatal is specified, warnings are treated as fatal errors.

lint-old

Like lint, but compares to an older version of awk used on Version 7 Unix.

non-decimal-data

When reading data, interpret numbers beginning with 0 to be octal, and those beginning with 0x to be hexadecimal. (To print nondecimal numbers, use the printf command, as print prints only string representations of nondecimal numbers.)

posix

Expect exact compatibility with POSIX; disable all gawk extensions as if traditional had been specified. Ignore \x escape sequences, **, **=, the keyword func, and single-tab field separators. Disallow newlines after ? or : and the fflush function.

profile[=file]

Write a pretty printed version of the script being executed to the specified file, or to the file awkprof.out in the current directory if no other file is specified. When gawk is invoked as pgawk and passed this version of the program with the -f option, it will add profile data to the file inserting execution counts to the left of each statement in the program.

re-interval

Allow use of {n,m} intervals in regular expressions.

source=script

Treat script as gawk commands. Like the 'script' argument, but lets you mix commands from files (using -f options) with commands on the gawk command line.

version

Print version information and exit.


13.2 Patterns and Procedures

gawk scripts consist of patterns and procedures:

pattern {procedure}

Both are optional. If pattern is missing, {procedure} is applied to all records. If {procedure} is missing, the matched record is printed. By default, each line of input is a record, but you can specify a different record separator through the RS variable.

13.2.1 Patterns

A pattern can be any of the following:

/regular expression/

relational expression

pattern-matching expression

pattern,pattern

BEGIN

END

Some rules regarding patterns include:

  • Expressions can be composed of quoted strings, numbers, operators, functions, defined variables, or any of the predefined variables described later under "gawk System Variables."

  • Regular expressions use the extended set of metacharacters and are described in Chapter 9.

  • In addition, ^ and $ can be used to refer to the beginning and end of a field, respectively, rather than the beginning and end of a record.

  • Relational expressions use the relational operators listed under "Operators" later in this chapter. Comparisons can be either string or numeric. For example, $2 > $1 selects lines for which the second field is greater than the first.

  • Pattern-matching expressions use the operators ~ (match) and !~ (don't match). See "Operators" later in this chapter.

  • The BEGIN pattern lets you specify procedures that take place before the first input record is processed. (Generally, you set global variables here.)

  • The END pattern lets you specify procedures that take place after the last input record is read.

  • If there are multiple BEGIN or END patterns, their associated actions are taken in the order in which they appear in the script.

  • pattern,pattern specifies a range of lines. This syntax cannot include BEGIN or END as a pattern.

Except for BEGIN and END, patterns can be combined with the Boolean operators || (OR), && (AND), and ! (NOT).

In addition to other regular-expression operators, GNU gawk supports POSIX character lists, which are useful for matching non-ASCII characters in languages other than English. These lists are recognized only within [ ] ranges. A typical use is [[:lower:]], which in English is the same as [a-z]. See Chapter 9 for a complete list of POSIX character lists.

13.2.2 Procedures

Procedures consist of one or more commands, functions, or variable assignments, separated by newlines or semicolons and contained within curly braces. Commands fall into four groups:

  • Variable or array assignments

  • Printing commands

  • Built-in functions

  • Control-flow commands

13.2.3 Simple Pattern/Procedure Examples

  1. Print first field of each line (no pattern specified):

    { print $1 }

  2. Print all lines that contain "Linux":

    /Linux/

  3. Print first field of lines that contain "Linux":

    /Linux/{ print $1 }

  4. Print records containing more than two fields:

    NF > 2

  5. Interpret each group of lines up to a blank line as a single input record:

    BEGIN { FS = "\n"; RS = "" }

  6. Print fields 2 and 3 in switched order, but only on lines whose first field matches the string "URGENT":

    $1 ~ /URGENT/ { print $3, $2 }

  7. Count and print the number of instances of "ERR" found:

    /ERR/ { ++x }; END { print x }

  8. Add numbers in second column and print total:

    {total += $2 }; END { print "column total is", total}

  9. Print lines that contain fewer than 20 characters:

    length( ) < 20

  10. Print each line that begins with "Name:" and that contains exactly seven fields:

    NF =  = 7 && /^Name:/

  11. Reverse the order of fields:

    { for (i = NF; i >= 1; i--) print $i }


13.3 gawk System Variables

Variable | Description
$n | nth field in current record; fields are separated by FS
$0 | Entire input record
ARGC | Number of arguments on command line
ARGIND | Current file's place in command line (starting with 0)
ARGV | An array containing the command-line arguments
CONVFMT | Conversion format for numbers (default is %.6g)
ENVIRON | An associative array of environment variables
ERRNO | Description of last system error
FIELDWIDTHS | List of field widths (whitespace-separated)
FILENAME | Current filename
FNR | Like NR, but relative to the current file
FS | Field separator (default is any whitespace; null string separates into individual characters)
IGNORECASE | If true, make case-insensitive matches
LINT | If true, run as if -W lint had been specified on the command line; if value is FATAL, generate fatal errors
NF | Number of fields in current record
NR | Number of the current record
OFMT | Output format for numbers (default is %.6g)
OFS | Output field separator (default is a blank)
ORS | Output record separator (default is a newline)
RLENGTH | Length of the string matched by match function
RS | Record separator (default is a newline)
RT | The input text matching the record separator (RS) for the current record
RSTART | First position in the string matched by match function
SUBSEP | Separator character for array subscripts (default is \034)


13.4 PROCINFO Array

gawk stores information about the current process in an array named PROCINFO. The array contains the following fields:

Field | Description
egid | Effective group ID
euid | Effective user ID
FS | The type of field splitting being used, either FS or FIELDWIDTHS
gid | Group ID of the calling process
groupn | Supplementary user group IDs associated with the process (group1, group2, etc.)
pgrpid | Process group ID
pid | Process ID
ppid | Parent process ID
uid | User ID of the calling process


13.5 Operators

The following table lists the operators, in order of increasing precedence, that are available in gawk.

Symbol | Meaning
= += -= *= /= %= ^= **= | Assignment
?: | C style conditional (expression ? if-true-action : if-false-action)
|| | Logical OR
&& | Logical AND
in | Array membership (see for command)
~ !~ | Match regular expression and negation
< <= > >= != == >> | | & | Relational and redirection operators
(blank) | Concatenation
+ - | Addition, subtraction
* / % | Multiplication, division, and modulus
+ - ! | Unary plus and minus and logical negation
^ ** | Exponentiation
++ -- | Increment and decrement, either prefix or postfix
$ | Field reference


13.6 Variable and Array Assignments

Variables can be assigned a value with an equals sign. For example:

FS = ","

Expressions using the operators +, -, /, and % (modulo) can be assigned to variables.

Arrays can be created with the split function (see the listing in the Section 13.8), or they can simply be named in an assignment statement. Array elements can be subscripted with numbers (array[1]) or with names. For example, to count the number of occurrences of a pattern, you could use the following script:

/pattern/ { array["/pattern/"]++ }

END { print array["/pattern/"] }

In gawk, variables need not be declared previous to their use, nor do arrays need to be dimensioned; they are activated upon first reference. All variables are stored as strings but may be used either as strings or numbers. gawk will use the program script context to determine whether to treat a variable as a string or a number, but the distinction also can be forced by the user. To force a variable to be treated as a string, concatenate a null to the variable:

var ""

To force a variable to be treated as a number, add 0 to it:

var + 0


13.7 Group Listing of gawk Commands

Arithmetic functions | String functions | Control flow statements | Input/output processing | Time functions | Miscellaneous
atan2 | asort | break | close | mktime | and
cos | gensub | continue | fflush | strftime | compl
exp | gsub | do/while | getline | systime | delete
int | index | exit | print |  | function
log | length | for | printf |  | lshift
rand | match | if | sprintf |  | or
sin | split | next |  |  | rshift
sqrt | strtonum | nextfile |  |  | system
srand | sub | return |  |  | xor
 | substr | while |  |  |
 | tolower |  |  |  |
 | toupper |  |  |  |


13.8 Alphabetical Summary of Commands

The following alphabetical list of statements and functions includes all that are available in gawk in Linux.

and
and(x,y)

Return the result of a bitwise AND of x and y.

asort
asort(array[,outarray])

Sort the values of the specified array and assign numeric indices according to each value's new position in the array. If an output array is specified, the array to be sorted is copied to the new array and the new array is sorted, leaving the original array unchanged.

atan2
atan2(y,x)

Return the arctangent of y/x in radians.

break
break

Exit from a while or for loop.

close
close(filename-expr)

close(command-expr)

Close a file read by a getline command or a pipe. Takes as an argument the same expression that opened the pipe or file.

compl
compl(value)

Return the bitwise complement of value.

continue
continue

Begin next iteration of while or for loop without reaching the bottom.

cos
cos(x)

Return the cosine of x, an angle in radians.

delete
delete array[element]

delete array

Delete element of array. If no element is specified, all elements are deleted.

do
do

    body

while (expr)

Looping statement. Execute statements in body, then evaluate expr. If expr is true, execute body again.

exit
exit

Do not execute remaining instruction, and read no new input. END procedures will be executed.

exp
exp(arg)

Return the natural exponent of arg (the inverse of log).

fflush
fflush(filename)

Flush output to filename; default is the standard output.

for
for (i=lower ; i<=upper ; i++)

    command

While the value of variable i is in the range between lower and upper, do command. A series of commands must be put within braces. <= or any relational operator can be used; ++ or -- can be used to increment or decrement the variable.

for
for (item  in array)

     command

For each item in an associative array, execute command. Multiple commands must be put inside braces. Refer to each element of the array as array[item]. Elements of gawk arrays are stored in an order that enables access of any element in essentially equivalent time. This order may appear to be indiscriminate; if the output is desired in sorted order, you must pipe it through the sort command.

function
function name(parameter-list) {

     statements

}

Create name as a user-defined function consisting of gawk statements that apply to the specified list of parameters. Gawk accepts func as a synonymn for function.

gensub
gensub(r,s,n,t)

Substitute s for the nth match of regular expression r in the string t. Leave t unchanged, but return new string as the result. If n is g or G, change all matches. If t is not supplied, it defaults to $0.

getline
getline [varhairsp;] [<file]

command | getline [var]

The first form reads input from file or the next file on the command line, and the second form reads the output of command. Both forms read one line at a time, and each time the statement is executed it gets the next line of input. The line of input is assigned to $0 and is parsed into fields, setting NF, NR, and FNR. If var is specified, the result is assigned to var, and neither $0 nor NF is changed. Thus, if the result is assigned to a variable, the current line does not change. getline is actually a function, and it returns 1 if it reads a record successfully, 0 at EOF, and -1 if for some reason it is unsuccessful.

gsub
gsub(r,s,t)

Globally substitute s for each match of the regular expression r in the string t. Return the number of substitutions. If t is not supplied, it defaults to $0.

if
if (condition)

    command1

[else

    command2]

If condition is true, execute command1; otherwise, execute command2. condition can be an expression using any of the relational operators <, <=, = =, !=, >=, or >, as well as the pattern-matching operator ~. A series of commands must be put within braces.

Example

The following line determines whether the first word in each line starts with A, uppercase or lowercase:

if ($1 ~ /[Aa]*/)
index
index(substr,str)

Return the position of a substring in a string. Returns 0 if substr is not contained in str.

int
int(arg)

Return the integer part of arg.

length
length(arg)

Return the length of arg. If arg is not supplied, $0 is assumed.

log
log(arg)

Return the natural logarithm of arg (the inverse of exp).

lshift
lshift(value, n)

Bitwise command. Return the result of shifting value to the left by n bits.

match
match(s,r)

Return position in s where regular expression r first matches, or 0 if no occurrences are found. Sets the value of RSTART and RLENGTH.

mktime
mktime(datestring)

Convert a date given in the form YYYY MM DD HH MM SS [DST] into a timestamp. The time is assumed to be in the local time zone. The daylight savings time value, DST, may be 1 (true), 0 (false) or -1 (autodetect).

next
next

Read next input line and start new cycle through pattern/procedures statements.

nextfile
nextfile

Skip to the next file on the gawk command line and start new cycle through pattern/procedures statements.

or
or(x,y)

Return the result of a bitwise OR of x and y.

print
print [args] [destination]

Print args on output. Literal strings must be quoted. Fields are printed in the order they are listed. If separated by commas in the argument list, they are separated in the output by the character specified by OFS. If separated by spaces, they are concatenated in the output. destination is a shell redirection or pipe expression (e.g., > file) that redirects the default output.

printf
printf[format [, expressions]]

Formatted print statement. Expressions or variables can be formatted according to instructions in the format argument. The number of expressions must correspond to the number specified in the format sections.

format follows the conventions of the C-language printf statement. Here are a few of the most common formats:

%s

A string.

%d

A decimal number.

%n.mf

A floating-point number. n is the total number of digits; m is the number of digits after the decimal point.

%[-]nc

n specifies minimum field length for format type c. - left-justifies value in field; otherwise, value is right-justified.

Field widths are adjustable. For example, %3.2f limits a floating-point number to a minimum width of three digits, with two digits after the decimal point.

format also can contain embedded escape sequences, \n (newline) and \t (tab) being the most common. Spaces and literal text can be placed in the format argument by quoting the entire argument. If there are multiple expressions to be printed, multiple formats should be specified.

Example

Using the script:

{printf ("The sum on line %s is %d.\n", NR, $1+$2)}

the following input line:

5   5

produces this output, followed by a newline:

The sum on line 1 is 10.
rand
rand( )

Generate a random number between 0 and 1. This function returns the same series of numbers each time the script is executed, unless the random number generator is seeded using the srand function.

return
return [expr]

Used at end of user-defined functions to exit function, returning the value of expr.

rshift
rshift(value, n)

Bitwise command. Return the result of shifting value to the right by n bits.

sin
sin(x)

Return the sine of x, an angle in radians.

split
split(string,array[,sep])

Split string into elements of array array[1],...,array[n]. The string is split at each occurrence of separator sep. If sep is not specified, FS is used. If sep is a null string, a split is performed on every character. The number of array elements created is returned.

sprintf
sprintf [format[, expression(s)]]

Return the value of one or more expressions using the specified format (see printf). Data is formatted but not printed.

sqrt
sqrt(arg)

Return square root of arg.

srand
srand(expr)

Use expr to set a new seed for random number generator. Default is time of day.

strftime
strftime([format[,timestamp]])

Format timestamp according to format. Return the formatted string. The timestamp is a time-of-day value in seconds since midnight, January 1, 1970, UTC. The format string is similar to that of sprintf. (See the example for systime.) If timestamp is omitted, it defaults to the current time. If format is omitted, it defaults to a value that produces output similar to that of date.

strtonum
strtonum(str)

Return the numeric value of string str. If str begins with 0 or 0x it will be treated as an octal or hexadecimal number. Trailing letters on str are ignored.

sub
sub(r,s,t)

Substitute s for first match of the regular expression r in the string t. Return 1 if successful; 0 otherwise. If t is not supplied, the default is $0.

substr
substr(string,m[,n])

Return substring of string beginning at character position m and consisting of the next n characters. If n is omitted, include all characters to the end of the string.

system
system(command)

Execute the specified shell command and return its status. The status of the command that is executed typically indicates success (1), completion (0), or unexpected error (-1). The output of the command is not available for processing within the gawk script.

systime
systime( )

Return number of seconds since midnight UTC, January 1, 1970.

Example

Log the start and end times of a data processing program:

BEGIN {

      now = systime( )

      mesg = strftime("Started at %m/%d/%Y %H:%M:%S", now)

      print mesg

}

process data ...

END {

      now = systime( )

      mesg = strftime("Ended at %m/%d/%Y %H:%M:%S", now)

      print mesg

}
tolower
tolower(str)

Translate all uppercase characters in str to lowercase and return the new string.

toupper
toupper(str)

Translate all lowercase characters in str to uppercase and return the new string.

while
while (condition)

  command

Execute command while condition is true (see if for a description of allowable conditions). A series of commands must be put within braces.

xor
xor(x,y)

Return the result of a bitwise XOR of x and y.


Chapter 14. RCS

The Revision Control System (RCS) offers version control (or revision control), a system that maintains information about a project's evolution so that project members can retrieve prior versions, track changes, and—most importantly— coordinate the efforts of the team. In a typical interaction, a developer checks out the most current code from the repository, makes changes, tests the results, and then commits those changes back to the repository when they are deemed satisfactory.

RCS can keep track of multiple file revisions, thereby reducing the amount of storage space needed. With RCS you can automatically store and retrieve revisions, merge or compare revisions, keep a complete history (or log) of changes, and identify revisions using symbolic keywords.

RCS preceded CVS and performs a similar role. RCS is more limited because it was designed to be used within a single directory and maintains a separate repository in each directory. Although RCS is no longer actively developed, it is still useful for small projects, offering fewer administrative issues than CVS. Projects with large directory structures or with team members on many different computer systems would benefit from using CVS, described in Chapter 15.

RCS uses a locking model to coordinate the efforts of multiple developers by serializing file modifications. Before making changes to a file, a developer must not only obtain a copy of it, but also request and obtain a lock on it from the system. This lock serves to prevent (or really, dissuade) multiple developers from working on the same file at the same time. When the changes are committed, the developer unlocks the file, permitting other developers to gain access to it.


14.1 Overview of RCS Commands

The three most important RCS commands are:

ci

Check in revisions (put a file under RCS control).

co

Check out revisions.

rcs

Set up or change attributes of RCS files.

Two additional commands provide information about RCS files:

ident

Extract keyword values from an RCS file.

rlog

Display a summary (log) about the revisions in an RCS file.

You can compare RCS files with these commands:

rcsdiff

Report differences between revisions.

rcsmerge

Incorporate changes from two RCS files into a third RCS file.

The following command helps with configuration management:

rcsclean

Remove working files that have not been changed.


14.2 Basic RCS Operations

Normally, you maintain RCS files in a subdirectory of your working directory called RCS, so the first step in using RCS should be:

mkdir RCS

Next, you place an existing file (or files) under RCS control by running the checkin command:

ci  file

This creates a file called file,v in directory RCS. file,v is called an RCS file, and it will store all future revisions of file. When you run ci on a file for the first time, you are prompted to describe the contents. ci then deposits file into the RCS directory as revision 1.1.

To edit a new revision, check out a copy:

co -l  file

This causes RCS to extract a copy of file from the RCS directory. You must lock the file with -l to make it writable by you. This copy is called a working file. When you're done editing, you can record the changes by checking the working file back in again:

ci  file

This time, you are prompted to enter a log of the changes made, and the file is deposited as revision 1.2. Note that a checkin normally removes the working file. To retrieve a read-only copy, do a checkout without a lock:

co  file

This is useful when you need to keep a copy on hand for compiling or searching. As a shortcut to the previous ci/co, you could type:

ci -u  file

This checks in the file but immediately checks out a read-only copy. To compare changes between a working file and its latest revision, you can type:

rcsdiff  file

Another useful command is rlog, which shows a summary of log messages.

System administrators can use the rcs command to set up default behavior for RCS.


14.3 General RCS Specifications

This section discusses:

  • Keyword substitution

  • Revision numbering

  • Specifying the date

  • Specifying states

  • Standard options and environment variables

14.3.1 Keyword Substitution

RCS lets you place keyword variables in your working files. These variables are later expanded into revision notes. You can then use the notes either as embedded comments in the input file or as text strings that appear when the output is printed. To create revision notes via keyword substitution, follow this procedure:

  1. In your working file, type any of the keywords listed in the next section.

  2. Check the file in.

  3. Check the file out again. Upon checkout, the co command expands each keyword to include its value. That is, co replaces instances of:

    $ keyword $

    with:

    $ keyword : value $

  4. Subsequent checkin and checkout of a file will update any existing keyword values. Unless otherwise noted later, existing values are replaced by new values.

Many RCS commands have a -k option that provides more flexibility during keyword substitution.

14.3.1.1 Keywords
$Author$

Username of person who checked in revision.

$Date$

Date and time of checkin.

$Header$

A title that includes the RCS file's full pathname, revision number, date, author, state, and (if locked) the person who locked the file.

$Id$

Same as $Header: /work/nutshell/qref.linux4/RCS/ch14,v 1.13 2003/05/23 19:00:11 emily Exp emily $, but excludes the full pathname of the RCS file.

$Locker$

Username of person who locked the revision. If the file isn't locked, this value is empty.

$Log$

The message that was typed during checkin to describe the file, preceded by the RCS filename, revision number, author, and date. Log messages accumulate rather than being overwritten.

$Name$

The symbolic name used to check out the revision, if there is one.

$RCSfile$

The RCS filename, without its pathname.

$Revision$

The assigned revision number.

$Source$

The RCS filename, including its pathname.

$State$

The state assigned by the -s option of ci or rcs.

14.3.1.2 Example values

Let's assume that the file /projects/new/chapter3 has been checked in and out by a user named daniel. Here's what keyword substitution would produce for each keyword, for the second revision of the file:

Author: daniel $

$Date: 2003/02/25 18:21:10 $

$Header: /projects/new/chapter3,v 1.2 2003/02/25 18:21:10 daniel \

    Exp Locker: daniel $

$Id: chapter3,v 1.2 2003/02/25 18:21:10 daniel Exp daniel $

$Locker: daniel $

$Log: chapter3,v $

#Revision 1.2  2003/02/25 18:21:10  daniel

#Added section on error-handling

#

#Revision 1.1  2003/02/25 16:49:59  daniel

#Initial revision

#

$RCSfile: chapter3,v $

$Revision: 1.2 $

$Source: /projects/new/chapter3,v $

$State: Exp $

14.3.2 Revision Numbering

Unless told otherwise, RCS commands typically operate on the latest revision. Some commands have an -r option that is used to specify a revision number. In addition, many options accept a revision number as an optional argument. (In the command summary, this argument is shown as [R].) Revision numbers consist of up to four fields—release, level, branch, and sequence—but most revisions consist of only the release and level.

For example, you can check out revision 1.4 as follows:

co -l -r1.4 ch01

When you check it in again, the new revision will be marked as 1.5. But suppose the edited copy needs to be checked in as the next release. You would type:

ci -r2 ch01

This creates revision 2.1. You can also create a branch from an earlier revision. The following command creates revision 1.4.1.1:

ci -r1.4.1 ch01

Numbers are not the only way to specify revisions, though. You can assign a text label as a revision name, using the -n option of ci or rcs. You can also specify this name in any option that accepts a revision number for an argument. For example, you could check in each of your C programs, using the same label regardless of the current revision number:

ci -u -nPrototype *.c

In addition, you can specify a $, which means the revision number is extracted from the keywords of a working file. For example:

rcsdiff -r$ ch01

compares ch01 to the revision that is checked in. You can also combine names and symbols. The command:

rcs -nDraft:$ ch*

assigns a name to the revision numbers associated with several chapter files.

14.3.3 Specifying the Date

Revisions are timestamped by time and date of checkin. Several keyword strings include the date in their values. Dates can be supplied in options to ci, co, and rlog. RCS uses the following date format as its default:

2002/10/16 02:00:00     (year/month/day time)

The default time zone is Greenwich Mean Time (GMT), which is also referred to as Coordinated Universal Time (UTC). Dates can be supplied in free format. This lets you specify many different styles. Here are some of the more common ones, which show the same time as in the preceding example:

6:00 pm lt          (assuming today is Oct. 16, 2002)

2:00 AM, Oct. 16, 2002

Wed Oct 16 18:00:00 2002 LT

Wed Oct 16 18:00:00 PST 2002

The uppercase or lowercase lt indicates local time (here, Pacific Standard Time). The third line shows ctime format (plus the LT); the fourth line is the date command format.

14.3.4 Specifying States

In some situations, particularly programming environments, you want to know the status of a set of revisions. RCS files are marked by a text string that describes their state. The default state is Exp (experimental). Other common choices include Stab (stable) or Rel (released). These words are user-defined and have no special internal meaning. Several keyword strings include the state in their values. In addition, states can be supplied in options to ci, co, rcs, and rlog.

14.3.5 Standard Options and Environment Variables

RCS defines the environment variable RCSINIT, which is used to set up default options for RCS commands. If you set RCSINIT to a space-separated list of options, these options will be prepended to the command-line options you supply to any RCS command. Four options are useful to include in RCSINIT: -q, -V, -x, and -z. They can be thought of as standard options because most RCS commands accept them.

-q[R]

Quiet mode; don't show diagnostic output. R specifies a file revision.

-V[n]

Emulate version n of RCS; useful when trading files between systems that run different versions. n can be 3, 4, or 5. If n is omitted, the command prints the version number of this version of RCS.

-xsuffixes

Specify an alternate list of suffixes for RCS files. Each suffix is separated by a /. On Unix systems, RCS files normally end with the characters ,v. The -x option provides a workaround for systems that don't allow a comma character in filenames.

For example, when depositing a working file into an RCS file, the command:

ci -x,v/ ch01       (second suffix is blank)

searches in order for the RCS filenames:

RCS/ch01,v

ch01,v

RCS/ch01
-z[zone]

Specify the format of the date in keyword substitution. If empty, the default is to output the UTC time with no zone indication. With an argument of LT, the local time zone will be used to output an ISO 8601 format, with an indication of the separation from UTC. You may also specify a numeric UTC offset. For example, -z+4:30 would output a string such as "2002-11-24 02:30:00+4:30".


14.4 Alphabetical Summary of RCS Commands

For details on the syntax of keywords, revision numbers, dates, states, and standard options, refer to the previous discussions.

ci
ci [options] files

Check in revisions. ci stores the contents of the specified working files into their corresponding RCS files. Normally, ci deletes the working file after storing it. If no RCS file exists, then the working file is an initial revision. In this case, the RCS file is created and you are prompted to enter a description of the file. If the RCS file exists, ci increments the revision number and prompts you to enter a message that logs the changes made. If a working file is checked in without changes, the file reverts to the previous revision.

The mutually exclusive options -u, -l, and -r are the most common. Use -u to keep a read-only copy of the working file (for example, so that the file can be compiled or searched). Use -l to update a revision and then immediately check it out again with a lock. This allows you to save intermediate changes but continue editing (for example, during a long editing session). Use -r to check in a file with a different release number. ci accepts the standard options -q, -V, -x, and -z.

Options

-d[date]

Check the file in with a timestamp of date or, if no date is specified, with the time of last modification.

-f[R]

Force a checkin even if there are no differences.

-I[R]

Interactive mode; prompt user even when standard input is not a terminal (e.g., when ci is part of a command pipeline).

-i[R]

Create (initialize) an RCS file and check it in. A warning is reported if the RCS file already exists.

-j[R]

Check in a file without initializing. Will report an error if file does not already exist.

-k[R]

Assign a revision number, creation date, state, and author from keyword values that were placed in the working file, instead of computing the revision information from the local environment. -k is useful for software distribution: the preset keywords serve as a timestamp shared by all distribution sites.

-l[R]

Do a co -l after checking in. This leaves a locked copy of the next revision in the working directory.

-mmsg

Use the msg string as the log message for all files checked in. When checking in multiple files, ci normally prompts whether to reuse the log message of the previous file. -m bypasses this prompting.

-M[R]

Set the working file's modification time to that of the retrieved version. Use of -M can confuse make and should be used with care.

-nname

Associate a text name with the new revision number.

-Nname

Same as -n, but override a previous name.

-r[R]

Check the file in as revision R.

-r

By itself, reverts to the default behavior of releasing a lock and removing the working file. This option overrides any -l or -u options that have been initialized by shell aliases or scripts. This behavior for -r is specific to ci.

-sstate

Set the state of the checked-in revision.

-tfile

Write the contents of file into the RCS file as the description, instead of prompting for it. This works only for the initial checkin.

-t-string

Write the specified string into the RCS file as the description, instead of prompting for it. This works only for initial checkin.

-T

Set the RCS file's modification time to the time of the latest revision if the RCS file's time precedes the new revision.

-u[R]

Do a co -u after checking in. This leaves a read-only copy in the working directory.

-wuser

Set the author field to user in the checked-in revision.

Examples

Check in chapter files using the same log message:

ci -m'First round edits' chap*

Check in edits to prog.c, leaving a read-only copy:

ci -u prog.c

Start revision level 2; refer to revision 2.1 as "Prototype":

ci -r2 -nPrototype prog.c
co
co [options] files

Retrieve a previously checked-in revision, and place it in the corresponding working file (or print to standard output if -p is specified). If you intend to edit the working file and check it in again, specify -l to lock the file. co accepts the standard options -q, -V, -x, and -z.

Options

-ddate

Retrieve latest revision whose checkin timestamp is on or before date.

-f[R]

Force the working file to be overwritten.

-I[R]

Interactive mode; prompt user even when standard input is not a terminal.

-jR2:R3

This works like rcsmerge. R2 and R3 specify two revisions whose changes are merged (joined) into a third file: either the corresponding working file or a third revision (any R specified by other co options).

-kc

Expand keyword symbols according to flag c, which can be:

b

Like o, but perform its operations in binary mode, generating the previous revision's keywords and values in binary.

k

Expand symbols to keywords only (no values). Useful for ignoring trivial differences during file comparison.

kv

Expand symbols to keyword and value (the default). Insert the locker's name only during a ci -l or co -l.

kvl

Like kv, but always insert the locker's name.

o

Expand symbols to keyword and value present in previous revision. This is useful for binary files that don't allow substring changes.

v

Expand symbols to values only (no keywords). This prevents further keyword substitution and is not recommended. Cannot be used with -l.

-l[R]

Same as -r, but also lock the retrieved revision.

-M[R]

Set the working file's modification time to that of the retrieved version. Use of -M can confuse make and should be used with care.

-p[R]

Send retrieved revision to standard output instead of to a working file. Useful for output redirection or filtering.

-r[R]

Retrieve the latest revision or, if R is given, retrieve the latest revision that is equal to or lower than R.

-sstate

Retrieve the latest revision having the given state.

-T

Preserve the modification time of the RCS file even if a lock is added or removed.

-u[R]

Same as -r, but also unlock the retrieved revision if you locked it previously.

-w[user]

Retrieve the latest revision that was checked in either by the invoking user or by the specified user.

Examples

Sort the latest stored version of file:

co -p  file  | sort

Check out (and lock) all uppercase filenames for editing:

co -l [A-Z]*

Note that filename expansion fails unless a working copy resides in the current directory. Therefore, this example works only if the files were previously checked in via ci -u. Finally, here are some different ways to extract the working files for a set of RCS files (in the current directory):

co -r3 *,v                    Latest revisions of release 3

co -r3 -wjim *,v              Same, but only if checked in by jim

co -d'May 5, 2 pm LT' *,v     Latest revisions that were modified

                              on or before the date

co -rPrototype *,v            Latest revisions named Prototype
ident
ident [option] [files]

Extract keyword/value symbols from files. files can be text files, object files, or dumps.

Options

-q

Suppress warning message when no keyword patterns are found.

-V

Print version information and exit.

Examples

If file prog.c is compiled, and it contains this line of code:

char rcsID[ ] = "$Author: daniel $";

then the following output is produced:

% ident prog.c prog.o

prog.c:

     $Author: daniel $

prog.o:

     $Author: daniel $

Show keywords for all RCS files (suppress warnings):

co -p RCS/*,v | ident -q
rcs
rcs [options] files

An administrative command for setting up or changing the default attributes of RCS files. Among other things, rcs lets you set strict locking (-L), delete revisions (-o), and override locks set by co (-l and -u). RCS files have an access list (created via -a); anyone whose username is on the list can run rcs. The access list is often empty, meaning that rcs is available to everyone. In addition, you can always invoke rcs if you own the file, if you're a privileged user, or if you run rcs with -i. rcs accepts the standard options -q, -V, -x, and -z.

Options

-ausers

Append the comma-separated list of users to the access list.

-Aotherfile

Append otherfile's access list to the access list of files.

-b[R]

Set the default branch to R or, if R is omitted, to the highest branch on the trunk.

-c'str'

Set the comment character to string str. This option is obsolete, because RCS normally uses the preceding $Log$ line's prefix when inserting log lines during checkout.

-e[users]

Erase everyone (or only the specified users) from the access list.

-i

Create (initialize) an RCS file, but don't deposit a revision.

-I

Interactive mode; prompt user even when standard input is not a terminal. (New in RCS Version 5.)

-kc

Use c as the default style for keyword substitution. (See co for values of c.) -kkv restores the default substitution style.

-l[R]

Lock revision R or the latest revision. -l "retroactively locks" a file and is useful if you checked out a file incorrectly by typing co instead of co -l. If another user already has a lock on the file, that lock is broken, as with -u.

-L

Turn on strict locking (the default). This means that everyone, including the owner of the RCS file, must use co -l to edit files. Strict locking is recommended when files are to be shared. (See -U.)

-mR:msg

Use the msg string to replace the log message of revision R.

-M

Disable email notification when breaking a lock on a file with rcs -u. This should be used only when there is another means to warn users that their files have been unlocked.

-nflags

Add or delete an association between a revision and a name. flags can be:

name:R

Associate name with revision R.

name:

Associate name with latest revision.

name

Remove association of name.

-Nflags

Same as -n, but overwrite existing names.

-oR_list

Delete (outdate) revisions listed in R_list. R_list can be specified as R1, R1:R2, R1:, or :R2. When a branch is given, -o deletes only the latest revision on it.

-sstate[:R]

Set the state of the latest revision, or revision R, to state.

-t[file]

Replace the RCS file description with the contents of file or, if no file is given, with standard input.

-t-string

Replace the RCS file description with string.

-T

Preserve the modification time of the RCS file unless a revision is removed.

-u[R]

The complement of -l: unlock a revision that was previously checked out via co -l. If someone else did the checkout, you are prompted to state the reason for breaking the lock. This message is mailed to the original locker.

-U

Turn on nonstrict locking. Everyone except the file owner must use co -l to edit files. (See -L.)

Examples

Associate the label To_customer with the latest revision of all RCS files:

rcs -nTo_customer: RCS/*

Add three users to the access list of file beatle_deals:

rcs -ageorge,paul,ringo beatle_deals

Delete revisions 1.2 through 1.5:

rcs -o1.2-1.5 doc

Replace an RCS file description with the contents of a variable:

echo "$description" | rcs -t  file
rcsclean
rcsclean [options] [files]

Compare checked-out files against the corresponding latest revision or revision R (as given by the options). If no differences are found, the working file is removed. (Use rcsdiff to find differences.) rcsclean is useful in makefiles. For example, you could specify a "clean-up" target to update your directories. rcsclean is also useful prior to running rcsfreeze. rcsclean accepts the standard options -q, -V, -x, and -z.

Options

-kc

When comparing revisions, expand keywords using style c. (See co for values of c.)

-n[R]

Show what would happen, but don't actually execute.

-r[R]

Compare against revision R. R can be supplied as arguments to other options, so -r is redundant.

-T

Preserve the modification time of the RCS file even if a lock is added or removed.

-u[R]

Unlock the revision if it's the same as the working file.

Examples

Remove unchanged copies of program and header files:

rcsclean *.c *.h
rcsdiff
rcsdiff [options] [diff_options] files

Compare revisions via diff. Specify revisions using -r as follows:

Number of revisions specified | Comparison made
0 | Working file against latest revision
1 | Working file against specified revision
2 | One revision against the other

rcsdiff accepts the standard options -q, -V, -x, and -z, as well as diff_options, which can include any valid diff option. rcsdiff exits with a status of 0 (no differences), 1 (some differences), or 2 (unknown problem).

Options

-kc

When comparing revisions, expand keywords using style c. (See co for values of c.)

-rR1

Use revision R1 in the comparison.

-rR2

Use revision R2 in the comparison. (-rR1 must also be specified.)

-T

Preserve the modification time on the RCS file.

rcsmerge
rcsmerge [options] file

Perform a three-way merge of file revisions, taking two differing versions and incorporating the changes into the working file. You must provide either one or two revisions to merge (typically with -r). Overlaps are handled the same as with merge, by placing warnings in the resulting file. rcsmerge accepts the standard options -q, -V, -x, and -z. rcsmerge exits with a status of 0 (no overlaps), 1 (some overlaps), or 2 (unknown problem).

Options

-kc

When comparing revisions, expand keywords using style c. (See co for values of c.)

-p[R]

Send merged version to standard output instead of overwriting file.

-r[R]

Merge revision R or, if no R is given, merge the latest revision.

Examples

Say you need to add updates to an old revision (1.3) of prog.c, but the current file is already at revision 1.6. To incorporate the changes:

co -l prog.c

(edit latest revision by adding revision 1.3 updates, then:)

rcsmerge -p -r1.3 -r1.6 prog.c > prog.updated.c

Undo changes between revisions 3.5 and 3.2, and overwrite the working file:

rcsmerge -r3.5 -r3.2 chap08
rlog
rlog [options] files

Display identification information for RCS files, including the log message associated with each revision, the number of lines added or removed, date of last checkin, and so on. With no options, rlog displays all information. Use options to display specific items. rlog accepts the standard options -V, -x, and -z.

Options

-b

Prune the display; print information about the default branch only.

-ddates

Display information for revisions whose checkin timestamps fall in the range of dates (a list separated by semicolons). Be sure to use quotes. Each date can be specified as:

date1<date2

Select revisions between date1 and date2, inclusive.

date1 <

Select revisions made on or after date1.

date1

Select revisions made on or before date1.

-h

Display only the beginning of the normal rlog listing, showing the RCS pathname, working pathname, header, default branch, etc.

-l[users]

Display information only about locked revisions or, if lockers is specified, only revisions locked by the comma-separated list of users.

-L

Skip files that aren't locked.

-N

Don't display symbolic names.

-r[list]

Display information for revisions in the comma-separated list of revision numbers. If no list is given, the latest revision is used. Items can be specified as:

R1

Select revision R1. If R1 is a branch, select all revisions on it.

R1.

If R1 is a branch, select its latest revision.

R1:R2

Select revisions R1 through R2.

:R1

Select revisions from beginning of branch through R1.

R1:

Select revisions from R1 through end of branch.

-R

Display only the name of the RCS file.

-sstates

Display information for revisions whose state matches one from the comma-separated list of states.

-t

Same as -h, but also display the file's description.

-w[users]

Display information for revisions checked in by anyone in the comma-separated list of users. If no users are supplied, assume the name of the invoking user.

Examples

Display a file's revision history:

rlog RCS/*,v | more

Display names of RCS files that are locked by user daniel:

rlog -R -L -ldaniel RCS/*

Display the "title" portion (no revision history) of a working file:

rlog -t calc.c


Chapter 15. CVS

The Concurrent Versions System (CVS) is the most popular revision control system among users of free and open source software. It is particularly appropriate for highly distributed projects, with developers working on many different computer systems and even in different parts of the world.

This chapter is based on CVS Version 1.11.2.


15.1 Basic Concepts

To accommodate large projects using a hierarchy of several directories, CVS defines the concepts repository and sandbox.

The repository (also called an archive) is the centralized storage area that stores the projects' files. It is managed by the version control system and the repository administrator, and contains information required to reconstruct historical versions of the files in a project. An administrator sets up and controls the repository using the procedures and commands described later in Section 15.5.

A sandbox (also called a working directory) contains copies of versions of files from the repository. New development occurs in sandboxes, and any number of sandboxes may be created from a single repository. The sandboxes are independent of one another and may contain files from different stages of the development of the same project. Users set up and control sandboxes using the procedures and commands found in the later Section 15.6.

In a typical interaction with CVS, a developer checks out the most current code from the repository, makes changes, tests the results, and then commits those changes back to the repository when they are deemed satisfactory.

15.1.1 Locking and Merging

Some systems, such as RCS (Revision Control System) and the older SCCS (Source Code Control System), use a locking model that coordinates the efforts of multiple developers by serializing file modifications. This was described at the beginning of the previous chapter. The locking model is pessimistic: it assumes that conflicts must be avoided. Serialization of file modifications through locks prevents conflicts. But it is cumbersome to have to lock files for editing when bug-hunting. Often, developers will circumvent the lock mechanism to keep working, which is an invitation to trouble.

To handle work by multiple developers on a single file, CVS uses a merging model that allows everyone to have access to the files at all times and supports concurrent development. The merging model is optimistic: it assumes that conflicts are not common and that when they do occur, it usually isn't difficult to resolve them.

CVS is capable of operating under a locking model via the -L and -l options to the admin command. Also, CVS has special commands (edit and watch) for those who want additional development coordination support. CVS uses locks internally to prevent corruption when multiple people are accessing the repository simultaneously, but this is different from the user-visible locks of the locking model.

15.1.2 Conflicts and Merging

In the event that two developers commit changes to the same version of a file, CVS automatically defers the commit of the second committer's file. The second committer then issues the cvs update command, which merges the first committer's changes into the local file. In many cases, the changes are in different areas of the file, and the merge is successful. However, if both developers have made changes to the same area of the file, the second to commit will have to resolve the conflict. This involves examining the problematic areas of the file and selecting among the multiple versions or making changes that resolve the conflict.

CVS detects only textual conflicts, but conflict resolution is concerned with keeping the project as a whole logically consistent. Therefore, conflict resolution sometimes involves changing files other than the one CVS complained about.

For example, if one developer adds a parameter to a function definition, it may be necessary for all the calls to that function to be modified to pass the additional parameter. This is a logical conflict, so its detection and resolution is the job of the developers (with support from tools like compilers and debuggers); CVS won't notice the problem.

In any merge situation, whether or not there was a conflict, the second developer to commit will often want to retest the resulting version of the project because it has changed since the original commit. Once it passes the test, the developer will need to recommit the file.

15.1.3 Tagging

CVS tracks file versions by revision number, which can be used to retrieve a particular revision from the repository. In addition, it is possible to create symbolic tags so that a group of files (or an entire project) can be referred to by a single identifier even when the revision numbers of the files are not the same (which is most often the case). This capability is often used to keep track of released versions or other important project milestones.

For example, the symbolic tag hello-1_0 might refer to revision number 1.3 of hello.c and revision number 1.1 of Makefile (symbolic tags are created with the tag and rtag commands).

15.1.4 Branching

The simplest form of development is linear development, in which there is a succession of revisions to a file, each derived from the prior revision. Many projects can get by with a completely linear development process, but larger projects (as measured by number of files, number of developers, and/or size of the user community) often run into maintenance issues that require additional capabilities. Sometimes it is desirable to do some speculative development while the main line of development continues uninterrupted. Other times, bugs in the currently released version must be fixed while work on the next version is already underway. In both of these cases, the solution is to create a branch (or fork) from an appropriate point in the development of the project. If, at a future point, some or all of the changes on the branch are needed on the main line of development (or elsewhere), they can be merged together (joined).

Branches are forked with the tag -b command; they are joined with the update -j command.


15.2 CVS Command Format

CVS commands are of the form:

cvs global_options command command_options

For example, here is a simple sequence of commands showing both kinds of options in the context of creating a repository, importing existing files, and performing a few common operations on them:

$ cvs -d /usr/local/cvsrep init

$ cd ~/work/hello

$ cvs -d /usr/local/cvsrep import -m 'Import' hello vendor start

$ cd ..

$ mv hello hello.bak

$ cvs -d /usr/local/cvsrep checkout hello

$ cd hello

$ vi hello.c

$ cvs commit -m 'Fixed a typo'

$ cvs tag hello-1_0

$ cvs remove -f Makefile

$ cvs commit -m 'Removed old Makefile'

$ cvs upd -r hello-1_0

$ cvs upd -A

Some global options are common to both user and administrator commands, and some are specific to each. The common global options are described in the next section, and the administrator and user options are described in Section 15.5 and Section 15.6, respectively.


15.3 Common Global Options

Table 15-1 lists the global options that apply to both user and administrator commands.

Table 15-1. Common global options

Option

Description

-b bindir

Location of external RCS programs. This option is obsolete, having been deprecated at CVS versions above 1.9.18.

-T tempdir

Absolute path for temporary files. Overrides the setting of $TMPDIR.

-v, --version

Display version and copyright information.


15.4 Gotchas

This section clarifies a few aspects of CVS that can sometimes cause confusion.

File orientation

While directories are supported, they are not versioned in the same way as traditional files are. This is particularly important in the early evolutionary stages of a project, when the structure may be in flux. Also, if the project is undergoing major changes, the structure is likely to change. See Section 15.5.4.

Text orientation

There is no equivalent to diff for binary files, although CVS's support for binary files is usually sufficient. Use admin -kb to tell CVS a file is binary.

Line orientation

Moving a segment of code from one place in a file to another is seen as a delete (from the old location) and an unrelated add (to the new location).

CVS is not syntax-aware

As far as CVS is concerned, small formatting changes are equivalent to sweeping logic changes in the same line ranges.


15.5 CVS Administrator Reference

This section provides details on creating and configuring repositories and performing other CVS administrative tasks. A single computer can run multiple copies of the CVS server, and each server can serve multiple repositories.

15.5.1 Creating a Repository

Select a directory that will contain the repository files (/usr/local/cvsrep is used in the following examples). Use the init command to initialize the repository. Either set the $CVSROOT environment variable to the absolute path of the repository:

$ export CVSROOT=/usr/local/cvsrep

$ cvs init

or use the -d option to specify the absolute path to the repository:

$ cvs -d /usr/local/cvsrep init

For information on importing code, see the Section 15.6, especially import and add.

15.5.1.1 Setting up the password server with inetd

If your server uses inetd to control services and you want users to access the repository from other computers, configure the pserver by doing the following as root:

  • Make sure there is an entry in /etc/services similar to the following:

    cvspserver 2401/tcp

  • If you are not using tcpwrappers, place a line like this in /etc/inetd.conf:

    cvspserver stream tcp nowait root /usr/bin/cvs cvs --allow-root=/usr/

local/cvsroot pserver

  • Or, if you are using tcpwrappers, use a line like this:

    cvspserver stream tcp nowait root /usr/sbin/tcpd /usr/bin/cvs

--allow-root=/usr/local/cvsroot pserver

  • Once these changes are in place, restart inetd (or send it the appropriate signal to cause it to reread inetd.conf).

15.5.1.2 Setting up the password server with xinetd

If your server uses xinetd to control services and you want users to access the repository from other computers, configure the pserver by doing the following as root:

  • Make sure there is a file /etc/xinetd.d/cvspserver similar to the following:

    service cvspserver

{

  port        = 2401

  socket_type = stream

  protocol    = tcp

  wait        = no

  user        = root

  passenv     = PATH

  server      = /usr/local/bin/cvs

  server_args = -f --allow-root=/usr/local/cvsroot pserver

}

  • Once these changes are in place, restart xinetd (or send it the appropriate signal to cause it to reread its configuration.

15.5.2 Security Issues

The following security issues need to be considered when working with CVS:

  • The contents of files will be transmitted in the open over the network with pserver and rsh. With pserver, passwords are transmitted in the open as well.

  • When using a local repository (i.e., when CVS is not being used in client/server mode), developers need write access to the repository, which means they can hack it.

  • The CVS server runs as root briefly before changing its user ID.

  • The ~/.cvspass file must be kept unreadable by all users except the owner to prevent passwords from being accessible.

  • A user who has authority to make changes to the files in the CVSROOT module can run arbitrary programs.

  • Some of the options to the admin command are very dangerous, so it is advisable to restrict its use. This can be accomplished by creating a user group named cvsadmin. If this user group exists, only users in that group can run the admin command (except admin -kkflag, which is available to everyone).

15.5.3 Repository Structure

The CVS repository is implemented as a normal directory with special contents. This section describes the contents of the repository directory.

15.5.3.1 The CVSROOT directory

The CVSROOT directory contains the administrative files for the repository; other directories in the repository contain the modules. The administrative files permit (and ignore) blank lines and comment lines in addition to the lines containing real configuration information. Comment lines start with a hash mark (#).

Some of the administrative files contain filename patterns to match file and directory names. These patterns are regular expressions like those used in GNU Emacs. Table 15-2 contains the special constructions used most often.

Table 15-2. Filename pattern special constructions

Construction

Description

^

Match the beginning of the string.

$

Match the end of the string.

.

Match any single character.

*

Modify the preceding construct to match zero or more repetitions.

CVS will perform a few important expansions in the contents of the administrative files before interpreting the results. First, the typical shell syntax for referring to a home directory is ~/, which expands to the home directory of the user running CVS, and ~user expands to the home directory of the specified user.

In addition, CVS provides a mechanism similar to the shell's environment variable expansion capability. Constructs such as ${variable} will be replaced by the value of the named variable. Variable names start with letters and consist entirely of letters, numbers, and underscores. Curly brackets may be omitted if the character immediately following the variable reference is not a valid variable name character. While this construct looks like a shell environment variable reference, the full environment is not available. Table 15-3 contains the built-in variables.

Table 15-3. Administrative file variables

Variable

Description

CVSEDITOREDITORVISUAL

The editor CVS uses for log file editing.

CVSROOT

The repository locator in use.

USER

The name of the user (on the server, if using a remote repository) running CVS.

=var

The value of a user-defined variable named var. Values for these variables are provided by the global -s option.

To edit these files, check out the CVSROOT module from the repository, edit the files, and commit them back to the repository. You must commit the changes for them to affect CVS's behavior.

Table 15-4 describes the administrative files and their functions.

Table 15-4. CVSROOT files

File

Description

checkoutlist

Extra files to be maintained in CVSROOT.

commitinfo

Specifications for commit governors.

config

Settings to affect the behavior of CVS.

cvsignore

Filename patterns of files to ignore.

cvswrappers

Specifications for checkout and commit filters.

editinfo

Specifications for log editors (obsolete).

history

Log information for the history command.

loginfo

Specify commit notifier program(s).

modules

Module definitions.

notify

Notification processing specifications.

passwd

A list of users and their CVS-specific passwords.

rcsinfo

Template form for log messages.

readers

A list of users having read-only access.

taginfo

Tag processing specifications.

users

Alternate user email addresses for use with notify.

verifymsg

Specify log message evaluator program.

writers

A list of users having read/write access.

Since the editinfo file is obsolete, use the $EDITOR environment variable (or the -e option) to specify the editor and the verifymsg file to specify an evaluator.

Each line of the taginfo file contains a filename pattern and a command line to execute when files with matching names are tagged.

15.5.3.2 The checkoutlist file

Whenever changes to files in the CVSROOT module are committed, CVS prints the message:

cvs commit: Rebuilding administrative file database

This informs you that the checked-out copy in the repository has been updated to reflect any changes just committed. As with any other module directory in the repository, the CVSROOT directory contains RCS (*,v) files that retain the history of the files. But to use the files, CVS needs a copy of the latest revision. So, when CVS prints this message, it is checking out the latest revisions of the administrative files.

If you have added files to the CVSROOT module (such as scripts to be called via entries in the loginfo file), you will need to list them in the checkoutlist file. This makes CVS treat them the same way as it treats the standard set of CVSROOT files.

Each line in this file consists of a filename and an optional error message that is displayed in case there is trouble checking out the file.

15.5.3.3 The commitinfo file

Whenever a commit is being processed, CVS consults this file to determine whether or not any precommit checking of the file is required. Each line of the file contains a directory name pattern, followed by the path of a program to invoke when files are commited in directories with matching names.

Aside from the usual filename-pattern syntax, there are two special patterns:

ALL

If this pattern is present in the file, all files are passed to the specified checking program. CVS then looks for a pattern that matches the name of each particular file and runs the additional checks found, if any.

DEFAULT

If this pattern is present in the file, all files for which there was no pattern match are sent to the specified checking program. The automatic match of every file to the ALL entry, if any, does not count as a match when determining whether or not to send the file to the DEFAULT checking program.

CVS constructs the command line for the checking program by appending the full path to the directory within the repository and the list of files being committed (this means you can specify the first few command-line arguments to the program, if necessary). If the checking program exits with a nonzero status, the commit is aborted.

The programs that run via this mechanism run on the server computer when a remote repository is used. Here is an example of a commitinfo file:

ALL $CVSROOT/CVSROOT/commit-ALL.pl

DEFAULT $CVSROOT/CVSROOT/commit-DEFAULT.pl

CVSROOT$ $CVSROOT/CVSROOT/commit-CVSROOT.pl

This example assumes you will create the script files in the CVSROOT module and add them to the checkoutlist file.

15.5.3.4 The config file

Repository configuration is specified in the config administrative file.

LockDir=dir

Directs CVS to put its lock files in the alternate directory given instead of in the repository itself, allowing users without write access to the repository (but with write access to dir) to read from the repository.

Version 1.11 supports this option. Version 1.10 doesn't support alternate directories for lock files and reports an error if this option is set. Older versions of CVS (1.9 and previous) don't support this option either and will not report an error. Do not mix versions that support alternate directories for lock files with versions that don't, since lock files in both places defeat the purpose of having them.

LogHistory=types

Determines the types of activities that will be logged to the history administrative file. The special value all implies all the record types listed in Tables Table 15-19, Table 15-20, and Table 15-21. Any subset of those record types can be specified by listing them. For example, the line LogHistory=MAR will log commit-related events only.

SystemAuth=value

CVS tries to authenticate users via the CVSROOT/passwd file first; if that fails and this option is set to yes, CVS tries to authenticate via the system's user database. This option is used with the password server. The default is yes.

TopLevelAdmin=value

If this option is set to yes, an additional CVS directory is created at the top-level directory when checkout is run. This allows the client software to detect the repository locator in that directory (see Section 15.6.1). The default is no.

This option is useful if you check out multiple modules to the same sandbox directory. If it is enabled, you won't have to provide a repository locator after the first checkout; CVS infers it from the information in the top-level CVS directory created during the first checkout.

15.5.3.5 The cvsignore file

The cvsignore administrative file contains a list of filename patterns to ignore, just like the .cvsignore files that can appear in sandboxes and user home directories. Unlike the filename patterns in other administrative files, these patterns are in sh syntax; they are not GNU Emacs-style regular expressions. There can be multiple patterns on a line, separated by whitespace (consequently, the patterns themselves cannot contain whitespace).

There is a slight difference between filename patterns in sh and CVS. Since the CVS patterns are not subject to variable interpolation, a pattern such as _$* (which is one of the patterns built into CVS) will match a file named _$foo but not one named _. But, if you present the same pattern to sh, the $* part will be interpolated resulting in an effective pattern of just _, which will then match the file _, but not _$foo. This becomes particularly important if you are writing your own utilities to work with CVS and you need to implement the same policy for ignoring files.

Table 15-5 shows the most commonly used sh-style pattern constructs.

Table 15-5. Filename patterns for cvsignore

Construct

Description

?

Any one character.

*

Any sequence of zero or more characters.

Again, diverging from the standards used by the rest of the administrative files, the cvsignore file does not support comments.

15.5.3.6 The cvswrappers file

While the cvsignore file allows CVS to ignore certain files, the cvswrappers file allows you to give CVS default options for commands that work with files. Lines in this file consist of a sh-style filename pattern followed by a -k (keyword substitution mode) option and/or an -m (update method) option. The legal values for -k are described in Table 15-17. The legal values for -m are COPY and MERGE.

If -m COPY is specified, CVS will not attempt to merge the files. Instead, it presents the user with conflicting versions of the file, and the user can choose one or the other or resolve the conflict manually.

For example, to treat all files ending in .jpg as binary, add this line to the file:

*.jpg -k b
15.5.3.7 The history file

If this file exists, CVS inserts records of activity against the repository. This information produces displays of the cvs history command. The history file is not intended for direct reading or writing by programs other than CVS.

A repository set up with cvs init automatically has a history file.

15.5.3.8 The loginfo file

The loginfo administrative file works much like the commitinfo file and can use the special patterns ALL and DEFAULT. This file allows you to do something with commit log messages and related information.

The programs called during loginfo processing receive the log message on standard input. Table 15-6 shows the three codes that can pass additional information to the called programs via command-line arguments.

Table 15-6. Special loginfo variables

Variable

Description

s

Filename

V

Pre-commit revision number

v

Post-commit revision number

If a percent sign (%) followed by the desired variable is placed after the command path, CVS inserts the corresponding information as a whitespace-separated list with one entry for each file, preceded by the repository path (as with commitinfo). There can be only one percent sign on the command line, so if you want information from more than one variable, place the variable names inside curly brackets: %{...}. In this case, each file-specific entry has one field for each variable, separated by commas. For example, the code %{sVv} expands into a list like this:

/usr/local/cvsrep/hello Makefile,1.1,1.2 hello.c,1.8,1.9

It can be helpful to send email notifications each time someone commits a file to the repository. Developers can monitor this stream of notices to determine when they should pull the latest development code into their private sandboxes. For example, consider a developer doing some preparatory work in his sandbox while he awaits stabilization and addition of another developer's new library. As soon as the new library is added and committed, email notification goes out, and the waiting developer sees that the code is ready to use. So, he runs cvs upd -d in the appropriate directory to pull in the new library code and then sets about integrating it with his work.

It is simple to set up this kind of notification. Just add a line like this to the CVSROOT/loginfo file:

DEFAULT mail -s %s developers@company.com

Often, the email address is a mailing list, which has all the interested parties (developers or otherwise) on the distribution list. If you want to send messages to multiple email addresses, you can write a script to do that and have that script called via this file. Alternatively, you can use the log.pl program that comes as part of the CVS source distribution (located at /usr/local/src/cvs-1.11/contrib/log.pl, assuming CVS was unpacked into /usr/local/src). Instructions for its use are provided as comments in the file.

15.5.3.9 The modules file

The top-level directories in a repository are called modules. In addition to these physical modules, CVS provides a mechanism to create logical modules through the modules administrative file. Here are the three kinds of logical modules:

Alias

Alias modules are defined by lines of the form:

module_name -a alias_module ...

Using an alias module name in a CVS command is equivalent to using its component modules (after the -a option) directly.

Regular

Regular modules are defined by lines of the form:

module_name [options] directory file ...

Checking out module_name results in the specified files from directory being checked out into a directory named module_name. The intervening directories (if any) are not reflected in the sandbox.

Ampersand

Ampersand modules are defined by lines of the form:

module_name [options] &other_module ...

Checking out such a module results in a directory named module_name, which in turn contains copies of the other_module modules.

Table 15-7 shows the options that can define modules.

Table 15-7. Module options

Option

Description

-d name

Override the default working directory name for the module.

-e prog

Run the program prog when files are exported from the module; the module name is passed in to prog as the sole argument.

-i prog

Run the program prog when files are committed to the module; the repository directory of the committed files is passed in to prog as the sole argument.

-i prog

Run the program prog when files are checked out from the module; the module name is passed in to prog as the sole argument.

-s status

Assign a status descriptor to the module.

-t prog

Run the program prog when files are tagged in the module using rtag; the module name and the symbolic tag are passed in to prog.

-u prog

Run the program prog when files are updated in the module's top-level directory; the full path to the module within the repository is passed in to prog as the sole argument.

Alias modules provide alternative names for other modules or shortcuts for referring to collections or subdirectories of other modules. Alias module definitions function like macro definitions in that they cause commands to run as if the expanded list of modules and directories were on the command line. Alias modules do not cause the modules of their definition to be grouped together under the alias name (use ampersand modules for that). For example, the definition:

h -a hello

makes the name h a synonym for the hello module. This definition:

project -a library client server

allows you to check out all three modules of the project as a unit. If an entry in the definition of an alias module is preceded by an exclamation point (!), then the named directory is excluded from the module.

Regular modules allow you to create modules that are subsets of other modules. For example, the definition:

header library library.h

creates the header module, which consists of only the library.h file from the library module.

Ampersand modules are true logical modules. There are no top-level directories for them in the repository, but you can check them out to sandboxes, and directories with their names will then appear. The modules listed in the definition are below that directory. For example:

project &library &client &server

is almost the same as the alias module example given earlier, except that the submodules are checked out inside a subdirectory named project.

In this file, long definitions may be split across multiple lines by terminating all but the last line with backslashes (\).

15.5.3.10 The notify file

This file is used in conjunction with the watch command. When notifications are appropriate, this file is consulted to determine how to do the notification.

Each line of the notify file contains a filename pattern and a command line. CVS's notification mechanism uses the command line specified to perform notifications for files with names that match the corresponding pattern.

There is a single special-purpose variable, %s, that can appear in the command specification. When the command is executed, the name of the user to notify replaces the variable name. If the users administrative file exists, the usernames are looked up there, and the resulting values are used for %s instead. This allows emails to be sent to accounts other than those on the local machine. Details are sent to the notification program via standard input.

Typical usage of this feature is the single entry:

ALL mail %s -s "CVS notification"

In fact, this entry is present in the default notify file created when you run cvs init to create a repository (although it is initially commented out).

15.5.3.11 The passwd file

If you access the repository via a pserver repository locator (see Section 15.6.1), then CVS can have its own private authentication information, separate from the system's user database. This information is stored in the CVSROOT/passwd administrative file.

This feature provides anonymous CVS access over the Internet. By creating an entry for a public user (usually anoncvs or anonymous), the pserver can be used by many people sharing the public account. If you don't want to create a system user with the same name as the public user, or if you have such a user but it has a different purpose, you can employ a user alias to map it to something else:

anonymous:TY7QWpLw8bvus:cvsnoname

Then, make sure you create the cvsnoname user on the system. You can use /bin/false as the login shell, and the repository's root directory as the home directory for the user.

If you leave the password field empty for the anonymous user, then CVS will accept any password (as of Version 1.11). To restrict the public user to read-only access, list it in the CVSROOT/readers administrative file.

Additionally, CVS's private user database is useful even if you don't want to set up anonymous CVS access. You can restrict access to a subset of the system's users, provide remote access to users who don't have general system access, or prevent a user's normal system password from being transmitted in the clear over the network (see Section 15.5.2).

There is no cvs passwd command for setting CVS-specific passwords (located in the repository file CVSROOT/passwd). CVS-specific user and password management is a manual task.

15.5.3.12 The rcsinfo file

CVS consults this file when doing a commit or import to determine the log message editor template. Each entry in the file consists of a filename pattern and the name of the file to use as the template for module directories with matching names.

The ALL and DEFAULT special patterns apply to this file.

15.5.3.13 The readers file

If this file exists, users listed in it have read-only access.

15.5.3.14 The taginfo file

CVS consults this file whenever the tag or rtag commands are used. Entries in this file are filename patterns and program specifications. The ALL special pattern applies to this file.

The taginfo file is called with the tag, the operation being performed, the module directory name (relative to the repository root), and the filename and revision number for each affected file. The valid operations are add (for tag), del (for tag -d), and mov (for tag -F).

If the taginfo program returns a nonzero status, the tag or rtag command that caused its execution is aborted.

15.5.3.15 The users file

If this file exists, it is consulted during processing of the notify administrative file's contents. Entries in this file consist of two colon-separated fields on a single line. The first field is the name of a user, and the second field is a value (normally the user's email address on another machine). For example:

john:john@somecompany.com

jane:jane@anothercompany.com
15.5.3.16 The verifymsg file

CVS consults this file to determine if log messages should be validated. If the program returns a nonzero status, the commit is aborted. The verifymsg file is called with the full path to a file containing the log message to be verified.

The ALL special pattern is not supported for this file, although DEFAULT is. If more than one pattern matches, the first match is used.

15.5.3.17 The writers file

If this file exists, users listed in it have read/write access (unless they are also listed in the readers file, in which case they have read-only access).

15.5.4 Hacking the Repository

Since the repository is a normal directory, albeit one with special contents, it is possible to cd into the directory and examine its contents and/or make changes to the files and directories there. For each file that has been added there will be a file with the same name followed by ,v in a corresponding directory in the repository. These are RCS (the format, not the program) files that contain multiple versions of the file.

Since the activities discussed in this section involve making changes directly to the repository instead of working through CVS commands, you should exercise extreme caution and have current backups when following these instructions.

15.5.4.1 Restructuring a project

Restructuring the project by moving files and directories around (and possibly renaming them) in the repository will allow the files to retain their history. The standard way to rename a file when using CVS is to rename the file in the sandbox and do a cvs remove on the old name and a cvs add on the new name. This results in the file being disconnected from its history under the new name, so sometimes it is better to do the renaming directly in the repository. However, doing this while people have active sandboxes is dangerous, as the sandboxes will contain information about a file that is no longer in the repository.

15.5.4.2 Obsolete and temporary files

When importing an entire project, all of the project's files will be added to the repository; however, if some of these files shouldn't have been added, you'll want to remove them. Doing a cvs remove will accomplish this, but copies of those files will remain in the repository's .Attic directory forever. To avoid this, you can delete the files from the repository directly before checking out sandboxes from it.

15.5.5 Importing

If you have an existing code base, you'll want to import it into CVS in a way that preserves the most historical information. This section provides instructions for importing projects into CVS from code snapshots or other version control systems. Except for the code snapshot import procedure, all of these are based upon conversion to RCS files, followed by placing the RCS files in the proper location in the CVS repository.

15.5.5.1 Importing code snapshots

If you have maintained project history archives manually by taking periodic snapshots of the code, you can import the first snapshot, tag it with the date or version number, and then successively overlay the updated files from later archives. Each set can then be committed and tagged in order to bootstrap a repository that maintains the prior history.

For example, first unpack the distributions (this assumes they unpack to directories containing the version numbers):

$ tar xvzf foo-1.0.tar.gz

$ tar xvzf foo-1.1.tar.gz

$ tar xvzf foo-2.0.tar.gz

Next, make a copy of the first version, import it into the CVS repository, check it out to make a sandbox (since importing doesn't convert the source directory into a sandbox), and use cvs tag to give it a symbolic name reflecting the project version:

$ mkdir foo

$ cp -R -p foo-1.0/* foo

$ cd foo

$ cvs import -m 'Imported version 1.0' foo vendor start

$ cd ..

$ mv foo foo.bak

$ cvs checkout foo

$ cd foo

$ cvs tag foo-1_0

$ cd ..

Now, apply the differences between Version 1.0 and 1.1 to the sandbox, commit the changes, and create a tag:

$ diff -Naur foo-1.0 foo-1.1 | (cd foo; patch -Np1)

$ cd foo

$ cvs commit -m 'Imported version 1.1'

$ cvs tag foo-1_1

$ cd ..

Apply the differences between Version 1.1 and 2.0 to the sandbox, commit the changes, and create a tag:

$ diff -Naur foo-1.1 foo-2.0 | (cd foo; patch -Np1)

$ cd foo

$ cvs commit -m 'Imported version 2.0'

$ cvs tag foo-2_0

You can now use the log command to view the history of the files, browse past versions of the files, and continue development under version control.

15.5.5.2 Importing from RCS

If you are migrating from RCS to CVS, following these instructions will result in a usable CVS repository. This procedure involves direct modification of the CVS repository, so it should be undertaken with caution.

Before beginning, make sure none of the files to be imported into CVS is locked by RCS. Then, create a new CVS repository and module (or a new module within an existing repository). Next, create directories in the CVS repository to mirror the project's directory structure. Finally, copy all the version files (,v) from the project (which may be in RCS subdirectories) into the appropriate directories in the repository (without RCS subdirectories).

For example, first move aside the directory under RCS control, create an empty directory to build the new CVS structure, import the directory, and then check it out to make a sandbox:

$ mv foo foo-rcs

$ mkdir foo

$ cd foo

$ cvs import -m 'New empty project' foo vendor start

$ cd ..

$ mv foo foo.bak

$ cvs checkout foo

Next, make directories and add them to the repository to match the structure in the RCS project:

$ cd foo

$ mkdir dir

$ cvs add dir

$ cd ..

Now, copy the ,v files from the RCS project into the repository for the CVS project:

$ cp -p foo-rcs/*,v $CVSROOT/foo

$ cp -p foo-rcs/dir/*,v $CVSROOT/foo/dir

Finally, issue the cvs update command in the sandbox directory to bring in the latest versions of all the files:

$ cd foo

$ cvs upd
15.5.5.3 Importing from SCCS

To import from SCCS, use the sccs2rcs script located in the contrib directory of the CVS distribution to convert the files to RCS format, and then follow the preceding RCS procedure. You must have both CVS and SCCS installed for this to work. The script's comments contain additional instructions.

15.5.5.4 Importing from PVCS

To import from PVCS, use the pvcs_to_rcs script located in the contrib directory of the CVS distribution to convert the files to RCS format, and then follow the preceding RCS procedure. You must have both CVS and PVCS installed for this to work. The script's comments contain additional instructions.

15.5.6 Using an Interim Shared Sandbox

Projects will sometimes develop unintended environmental dependencies over time, especially when there is no pressure for the code to be relocatable. A project developed outside version control may even be initially developed in place (at its intended installation location). While these practices are not recommended, they do occur in real-world situations. CVS can help to improve the situation by encouraging relocatability from the beginning of a project.

The default mode of operation for CVS is multiple independent sandboxes, all coordinated with a central shared repository. Code that runs in this environment is necessarily (at least partially) relocatable. So, using CVS from the beginning of a project helps ensure flexibility.

However, if a project is already well underway, an interim approach can be used. For example, you could convert the development area to a single shared sandbox by importing the code into CVS and checking it back out again:

$ cd /usr/local/bar

$ cvs import bar vendor start

$ cd ..

$ mv bar bar.bak

$ cvs checkout bar

Chances are good that this approach is too aggressive and will check in more files than absolutely necessary. You can either go back and hack the repository to remove the files that shouldn't be there, or just issue the cvs remove command to delete them as you discover them.

In addition, there will probably be some binary files in the sandbox that were imported as text files. Wherever you see a binary file that needs to remain in the repository, you should issue the command cvs admin -kb file, then make a fresh copy from the project backup. Finally, issue the command cvs commit file to commit the fixed file back to the repository.

Having version control in place before making flexibility enhancements is a good idea, as it makes it easier to find (and possibly reverse) changes that cause trouble.

The repository locator (see Section 15.6.1) is specified via the -d option or the $CVSROOT environment variable. It is stored in the various CVS/root sandbox files. If you are using the password server (pserver), the user ID of the person checking out the sandbox will be remembered. If more than one person is working with a particular sandbox, they will have to share an account for CVS access.

One way to do this is to have a neutral user account with a password known by everyone with CVS access. One person then issues the cvs login command with that user ID and password. Once you are no longer using a shared sandbox, this workaround won't be necessary. However, during the time you are using a shared sandbox, it is important that the developers type their real user IDs into their log messages, since all the changes will appear to have been made by the common user.

15.5.7 Global Server Option

The server has one global option: --allow-root=rootdir. This option is used to tell the CVS server to accept and process requests for the specified repository.

15.5.8 Administrator Commands

Table 15-8 lists the commands that CVS administrators can use to manage their repositories.

Table 15-8. Administrator commands

Command

Description

adminadmrcs

Perform administrative functions.

init

Create a new repository.

kserver

Run in Kerberos server mode.

pserver

Run in password server mode.

server

Run in remote server mode.

admin
admin

 [ -b[rev] ]

 [ -cstring ]

 [ -kkflag ]

 [ -l[rev] ]

 [ -L ]

 [ -mrev:msg ]

 [ -nname[:[rev]] ]

 [ -Nname[:[rev]] ]

 [ -orange ]

 [ -q ]

 [ -sstate[:rev]

 [ -t[file] ]

 [ -t-string ]

 [ -u[rev] ]

 [ -U ]

 [ files ... ]

The admin command is used to perform administrative functions. If a cvsadmin user group exists, then only the users in that group will be able to run admin with options other than -k. Options that may be used with the admin command are listed here.

-b[rev]

Set the default branch.

-cstring

Obsolete. Set the comment leader.

-kkflag

Set the default keyword substitution mode.

-l[rev]

Lock the specified revision.

-L

Enable strict locking.

-mrev:msg

Change the revision's log message.

-nname[:[rev]]

Give the specified branch or revision the symbolic name name.

-Nname[:[rev]]

The same as -n, except that if name is already in use, it is moved.

-orange

Delete revisions permanently.

-q

Don't print diagnostics.

-sstate[:rev]

Change the state of a revision.

-t[file]

Set the descriptive text in the RCS file.

-t-string

Set the descriptive text in the RCS file to string.

-u[rev]

Unlock the specified revision.

-U

Disable strict locking.

If the revision specified for -l is a branch, the latest revision on that branch will be used. If no revision is given, the latest revision on the default branch is used.

If the name given for -n is already in use, an error is generated. You can use -N to move a tag (change the revision associated with the tag); however, you should normally use cvs tag or cvs rtag instead.

The -o option is very dangerous and results in a permanent loss of information from the repository. Use it with extreme caution and only after careful consideration. See Table 15-9 for the various ways to specify ranges. There must not be any branches or locks on the revisions to be removed. Beware of interactions between this command and symbolic names.

If no file is specified for the -t option, CVS reads from standard input until it reaches the end of the file or a period on a line by itself.

The determination of the target revision for the -u option is the same as for -l.

Table 15-9. Range formats

Format

Description

rev1::rev2

Eliminate versions between rev1 and rev2, retaining only enough information to go directly from rev1 to rev2. The two specified versions are retained.

::rev2

The same as rev1::rev2, except the first revision is the branchpoint revision.

rev1::

The same as rev1::rev2, except the second revision is the end of the branch, and it is deleted instead of retained.

rev

Delete the specified revision.

rev1:rev2

The same as rev1::rev2, except the two named revisions are deleted as well.

:rev2

The same as ::rev2, except the named revision is deleted as well.

rev1:

The same as rev1::, except the named revision is deleted as well.

The following options are present in CVS for historical reasons and should not be used. (Using these options may corrupt the repository.)

-alogins

Append the logins to the RCS file's access list.

-Aoldfile

Append the access list of oldfile to the access list of the RCS file.

-e[logins]

Erase logins from the RCS file's access list, or erase all if a list is not provided.

-i

Create and initialize a new RCS file. Don't use this option. Instead, use add to add files to a CVS repository.

-I

Run interactively. This option doesn't work with client/server CVS and is likely to be removed in a future version.

-Vn

This option specified that the RCS files used by CVS should be made compatible with a specific version of RCS.

-xsuffixes

This option used to be described as determining the filename suffix for RCS files, but CVS has always used only ,v as the RCS file suffix.

init
init

Initializes the repository. Use the global -d option to specify the repository's directory if $CVSROOT isn't set appropriately.

The newly initialized repository will contain a CVSROOT module and nothing else. Once the repository is initialized, use other CVS commands to add files to it or to check out the CVSROOT module to make changes to the administrative files.

kserver
kserver

Operate as a server with Kerberos authentication, providing access to the repositories specified before the command with the --allow-root option. This command is used in the inetd.conf file, not on the command line. Another global option frequently used with this command is -T (see Table 15-1).

pserver
pserver

Operate as a password-authenticated server, providing access to the repositories specified before the command with the --allow-root option. This command is used in the inetd.conf file, not on the command line. Another global option frequently used with this command is -T (see Table 15-1).

server
server

The CVS client runs this command on the remote machine when connecting to a repository specified by an :ext: repository locator (usually via RSH or SSH).


15.6 CVS User Reference

This section provides details on connecting to a repository, the structure of sandboxes, and using the CVS commands.

15.6.1 Repository Locators

CVS currently supports six methods for the client to access the repository: local, forked, external, a password server, a GSS-API (Generic Security Services API) server, and a Kerberos 4 server (most Kerberos users will want to use GSS-API). Table 15-10 describes the various repository locator types and their respective access methods.

Table 15-10. Repository access types and methods

Method

Locator format

Description

Local

path

:local:path

If the repository directory is local to the computer from which you will access it (or appears local, such as an NFS or Samba mounted filesystem), the repository string is just the pathname of the repository directory, such as /usr/local/cvsrep, or it can use the :local: prefix.

Forked local

:fork:path

This type of locator is used primarily for debugging the CVS protocol code, as it causes CVS to start (fork) a separate process to work with the repository and communicates with it using the CVS remote protocol.

External

:ext:user@host:path

External repositories are accessed via a remote shell utility, usually rsh (the default) or ssh. The environment variable $CVS_RSH is used to specify the remote shell program.

Password server

:pserver:user@host:path

Password server repositories require authentication to a user account before allowing use of the repository. Public CVS servers are commonly configured this way so they can provide anonymous CVS access. See Section 15.5.3.11 earlier in this chapter for more information on anonymous CVS.

GSS-API server

:gserver:

This locator type is used for servers accessible via Kerberos 5 or other authentication mechanisms supported by GSS-API.

Kerberos server

:kserver:

This locator type is used for servers accessible via Kerberos 4.

15.6.2 Configuring CVS

CVS's behavior can be influenced by two classes of settings other than the command-line arguments: environment variables (see Table 15-11) and special files (see Table 15-12).

Table 15-11. Environment variables

Variable

Description

$CVS_CLIENT_LOG

Client-side debugging file specification for client/server connections. $CVS_CLIENT_LOG is the basename for the $CVS_CLIENT_LOG.in and $CVS_CLIENT_LOG.out files, which will be written in the current working directory at the time a command is executed.

$CVS_CLIENT_PORT

The port number for :kserver: locators.

$CVS_CLIENT_PORT doesn't need to be set if the kserver is listening on port 1999 (the default).

$CVS_IGNORE_REMOTE_ROOT

According to the change log, this variable was removed from CVS with Version 1.10.3.

$CVS_PASSFILE

Password file for :pserver: locators. This variable must be set before issuing the cvs login to have the desired effect. Defaults to $HOME/.cvspass.

$CVS_RCMD_PORT

For non-Unix clients, the port for connecting to the server's rcmd daemon.

$CVS_RSH

Remote shell for :ext: locators, if not rsh.

$CVS_SERVER

Remote server program for :ext: locators, if not cvs.

$CVS_SERVER_SLEEP

Server-side execution delay (in seconds) to allow time to attach a debugger.

$CVSEDITOR

Editor used for log messages; overrides $EDITOR.

$CVSIGNORE

A list of filename patterns to ignore, separated by whitespace. (See also cvsignore in Table 15-4 and .cvsignore in Table 15-12.)

$CVSREAD

Determines read-only (if the variable is set) or read/write (if the variable is not set) for checkout and update.

$CVSROOT

Default repository locator.

$CVSUMASK

Used to determine permissions for (local) repository files.

$CVSWRAPPERS

A list of filename patterns for the cvswrappers function. See also Section 15.5.3.

$EDITOR

Specifies the editor to use for log messages; see notes for $CVSEDITOR earlier in this table.

$HOME

On Unix, used to find the .cvsrc file.

$HOMEDRIVE

On Windows NT, used to find the .cvsrc file.

$HOMEPATH

On Windows NT, used to find the .cvsrc file.

$PATH

Used to locate programs to run.

$TEMP$TMP$TMPDIR

Location for temporary files. $TMPDIR is used by the server. On Unix, /tmp (and TMP on Windows NT) may not be overridden for some functions of CVS due to reliance on the system's tmpnam( ) function.

$VISUAL

Specifies the editor to use for log messages; see notes for $CVSEDITOR earlier in this table.

Despite the similarity in names, the $CVSROOT environment variable and the CVSROOT directory in a repository are not related to each other.

The "RSH" in the name of the $CVS_RSH environment variable doesn't refer to the particular program (rsh), but rather to the program CVS is supposed to use for creating remote shell connections (which could be some program other than rsh, such as ssh).

Because there is only one way to specify the remote shell program to use ($CVS_RSH) and because this is a global setting, users that commonly access multiple repositories may need to pay close attention to which repository they are using. If one repository requires one setting of this variable and another requires a different setting, you will have to change this variable between accesses to repositories requiring different settings. This aspect of the repository access method is not stored in the CVS/Root file in the sandbox (see Section 15.6.4.3, later in this chapter). For example, if you access some repositories via rsh and some via ssh, you can create the following two utility aliases (bash syntax):

$ alias cvs="export CVS_RSH=ssh; cvs"

$ alias cvr="export CVS_RSH=rsh; cvs"

Table 15-12 shows the files used by the CVS command-line client for server connection and client configuration information. These files reside in the user's home directory.

Table 15-12. Client configuration files

Option

Description

~/.cvsignore

Filename patterns of files to ignore.

~/.cvspass

Passwords cached by cvs login.

~/.cvsrc

Default command options.

~/.cvswrappers

User-specific checkout and commit filters.

The ~/.cvspass file is really an operational file, not a configuration file. It is used by the cvs client program to store the repository user account password between cvs login and cvs logoff.

Some common .cvsrc settings are:

update -dP

Bring in new directories and prune empty directories on cvs update.

diff -c

Give output in context diff format.

15.6.3 Creating a Sandbox

In order to use CVS, you must create a sandbox or have one created for you. This section describes sandbox creation, assuming there is already a module in the repository you want to work with. See the import command for information on importing a new module into the repository.

  1. Determine the repository locator. Talk to the repository administrator if you need help finding the repository or getting the locator syntax right.

  2. If this will be your main repository, set $CVSROOT; otherwise, use the -d option when running CVS commands that don't infer the repository from the sandbox files.

  3. Pick a module to check out.

  4. Pick a sandbox location, and cd to the parent directory.

  5. If the repository requires login, do cvs login.

  6. Run cvs checkout module.

For example:

$ export CVSROOT=/usr/local/cvsroot

$ cd ~/work

$ cvs checkout hello

15.6.4 Sandbox Structure

This section describes the files and directories that may be encountered in sandboxes.

15.6.4.1 .cvsignore files

Sandboxes may contain .cvsignore files. These files specify filename patterns for files that may exist in the sandbox but that normally won't be checked into CVS. This is commonly used to cause CVS to bypass derived files.

15.6.4.2 .cvswrappers files

Sandboxes may contain .cvswrappers files, which provide directory-specific file handling information like that in the repository configuration file cvswrappers (see Section 15.5.3.6 earlier in this chapter).

15.6.4.3 CVS directories

Each directory in a sandbox contains a CVS directory. The files in this directory (see Table 15-13) contain metadata used by CVS to locate the repository and track which file versions have been copied into the sandbox.

Table 15-13. Files in the CVS directories

File

Description

BaseBaserevBaserev.tmp

The Base directory stores copies of files when the edit command is in use. The Baserev file contains the revision numbers of the files in Base. The Baserev.tmp file is used in updating the Baserev file.

Checkin.progUpdate.prog

The programs specified in the modules file for options -i and -u, respectively (if any).

Entries

Version numbers and timestamps for the files as they were copied from the repository when checked out or updated.

Entries.BackupEntries.LogEntries.Static

Temporary and intermediate files used by CVS.

Notify

Notify.tmp

Temporary files used by CVS for dealing with notifications for commands such as edit and unedit.

Repository

The name by which the directory is known in the repository.

Root

The repository locator in effect when the sandbox was created (via cvs checkout).

Tag

Information about sticky tags and dates for files in the directory.

Template

Used to store the contents of the rcsinfo administrative file from the repository for remote repositories.

Since each sandbox directory has one CVS/Root file, a sandbox directory corresponds to exactly one repository. You cannot check out some files from one repository and some from another into a single sandbox directory.

15.6.5 Client Global Options

Table 15-14 lists the global options that control the operation of the CVS client program.

Table 15-14. Client global options

Option

Description

-a

Authenticate (gserver only).

-d root

Locate the repository. Overrides the setting of $CVSROOT.

-e editor

Specify message editor. Overrides the settings of $CVSEDITOR and $EDITOR.

-f

Don't read ~/.cvsrc. Useful when you have .cvsrc settings that you want to forgo for a particular command.

-H [command]--help [command]

Display help. If no command is specified, displays general CVS help, including a list of other help options.

-l

Don't log command in history.

-n

Don't change any files. Useful when you want to know ahead of time which files will be affected by a particular command.

-q

Be quiet.

-Q

Be very quiet. Print messages for serious problems only.

-r

Make new working files read-only.

-s variable=value

Set the value of a user variable to a given value. User variables can be used in the contents of administrative files.

-t

Trace execution. Helpful in debugging remote repository connection problems and, in conjunction with -n, in determining the effect of an unfamiliar command.

-w

Make new working files read/write. Overrides $CVSREAD. Files are read/write unless $CVSREAD is set or -r is specified.

-x

Encrypt. (Introduced in Version 1.10.)

-z gzip_level

Set the compression level. Useful when using CVS in client/server mode across slow connections.

15.6.6 Common Client Options

Table 15-15 and Table 15-16 describe the options that are common to many CVS commands. Table 15-15 lists the common options with a description of their function, while Table 15-16 lists which options can be used with the user commands. In the sections that follow, details are provided only for options that are not listed here or that do not function as described here.

Table 15-15. Common options

Option

Description

-D date

Use the most recent revision no later than date (see Section 15.6.6.1 for supported date formats).

-f

For commands that involve tags (via -r) or dates (via -D), include files not tagged with the specified tag or not present on the specified date. The most recent revision will be included.

-k kflag

Determine how keyword substitution will be performed. The space between -k and kflag is optional. See Table 15-17 for the list of keyword substitution modes.

-l

Do not recurse into subdirectories.

-n

Don't run module programs.

-R

Do recurse into subdirectories (the default). As of Version 1.11, CVS can work in sandboxes with directories checked out from different repositories.

-r rev

Use a particular revision number or symbolic tag.

Table 15-16 shows which common options are applicable to each user command.

Table 15-16. Common client option applicability

Command

-D

-f

-k

-l

-n

-R

-r

add

annotate

checkout

commit

diff

edit

editors

export

help

history

import

log

login

logout

rannotate

rdiff

release

remove

rlog

rtag

status

tag

unedit

update

version

watch

watchers

15.6.6.1 Date formats

CVS can understand dates in a wide variety of formats, including:

ISO standard

The preferred format is YYYY-MM-DD HH:MM, which would read as 2000-05-17, or 2000-05-17 22:00. The technical details of the format are defined in the ISO 8601 standard.

Email standard

17 May 2000. The technical details of the format are defined in the RFC 822 and RFC 1123 standards.

Relative

10 days ago, 4 years ago.

Common

month/day/year. This form can cause confusion because not all cultures use the first two fields in this order (1/2/2000 would be ambiguous).

Other

Other formats are accepted, including YYYY/MM/DD and those omitting the year (which is assumed to be the current year).

15.6.6.2 Keyword substitutions

Table 15-17 describes the keyword substitution modes that can be selected with the -k option. CVS uses keyword substitutions to insert revision information into files when they are checked out or updated.

Table 15-17. Keyword substitution modes

Mode

Description

b

Binary mode. Treat the file the same as with mode o, but also avoid newline conversion.

k

Keyword-only mode. Flatten all keywords to just the keyword name. Use this mode if you want to compare two revisions of a file without seeing the keyword substitution differences.

kv

Keyword-value mode. The keyword and the corresponding value are substituted. This is the default mode.

kvl

Keyword-value-locker mode. This mode is the same as kv mode, except it always adds the lock holder's user ID if the revision is locked. The lock is obtained via the cvs admin -l command.

o

Old-contents mode. Use the keyword values as they appear in the repository rather than generate new values.

v

Value-only mode. Substitute the value of each keyword for the entire keyword field, omitting even the $ delimiters. This mode destroys the field in the process, so use it cautiously.

Keyword substitution fields are strings of the form $Keyword ...$. The valid keywords are:

Author

The user ID of the person who committed the revision.

Date

The date and time (in standard UTC format) the revision was committed.

Header

The full path of the repository RCS file, the revision number, the commit date, time, and user ID, the file's state, and the lock holder's user ID if the file is locked.

Id

A shorter form of Header, omitting the leading directory name(s) from the RCS file's path, leaving only the filename.

Name

The tag name used to retrieve the file, or empty if no explicit tag was given when the file was retrieved.

Locker

The user ID of the user holding a lock on the file, or empty if the file is not locked.

Log

The RCS filename. In addition to keyword expansion in the keyword field, each commit adds additional lines in the file immediately following the line containing this keyword. The first such line contains the revision number and the commit date, time, and user ID. Subsequent lines are the contents of the commit log message. The result over time is a reverse-chronological list of log entries for the file. Each of the additional lines is preceded by the same characters that precede the keyword field on its line. This allows the log information to be formatted in a comment for most languages. For example:

#

# foo.pl

#

# $Log: ch15.xml,v $

#

#

# Revision 1.2  2000/06/09 22:10:23  me

# Fixed the new bug introduced when the last one was fixed.

#

# Revision 1.1  2000/06/09 18:07:51  me

# Fixed the last remaining bug in the system.

#

Be sure that you don't place any keyword fields in your log messages if you use this keyword, since they will get expanded if you do.

RCSfile

The name of the RCS file (without any leading directories).

Revision

The revision number of the file.

Source

The full path of the RCS file.

State

The file's state, as assigned by cvs admin -s (if you don't set the state explicitly, it will be Exp by default).

15.6.7 User Commands

The CVS client program provides the user commands defined in Table 15-18.

Table 15-18. User commands

Command

Description

adaddnew

Indicate that files/directories should be added to the repository.

annannotate

Display contents of the head revision of a file, annotated with the revision number, user, and date of the last change for each line.

checkoutcoget

Create a sandbox for a module.

cicomcommit

Commit changes from the sandbox back to the repository.

didifdiff

View differences between file versions.

edit

Prepare to edit files. This is used for enhanced developer coordination.

editors

Display a list of users working on the files. This is used for enhanced developer coordination.

exexpexport

Retrieve a module, but don't make the result a sandbox.

help

Get help.

hihishistory

Display the log information for files.

imimpimport

Import new modules into the repository.

lgnloginlogon

Log into (cache the password for) a remote CVS server.

lolog

Show the activity log for the file(s).

logout

Log off from (flush the password for) a remote CVS server.

papatchrdiff

Release diff. The output is the format of input to Larry Wall's patch command. Does not have to be run from within a sandbox.

rannotate

Display contents of the head revision of a module, annotated with the revision number, user, and date of the last change for each line.

rerelrelease

Perform a logged delete on a sandbox.

rlog

Show the activity log for the module(s).

removermdelete

Remove a file or directory from the repository.

rtrtagrfreeze

Tag a particular revision.

ststatstatus

Show detailed status for files.

tatagfreeze

Attach a tag to files in the repository.

unedit

Abandon file modifications and make read-only again.

upupdupdate

Synchronize sandbox to repository.

version

Display the version of the CVS client (and server, if appropriate) being used.

watch

Manage the watch settings. This is used for enhanced developer coordination.

watchers

Display the list of users watching for changes to the files. This is used for enhanced developer coordination.

add
add

 [ -k kflag ]

 [ -m message ]

 file ...

Indicate that files/directories should be added to the repository. They are not actually added until they are committed via cvs commit. This command is also used to resurrect files that have been deleted with cvs remove.

The standard meaning of the common client option -k applies. The only additional option that can be used with the add command is -m message. This option is used to provide a description of the file (which appears in the output of the log command).

annotate
annotate

 [ [ -D date | -r rev ] -f ]

 [ -F ]

 [ -l | -R ]

 file ...

CVS prints a report showing each line of the specified file. Each line is prefixed by information about the most recent change to the line, including the revision number, user, and date. If no revision is specified, the head of the trunk is used.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply. There is one additional option:

-F

Annotate binary files. CVS normally skips binary files.

checkout
checkout

 [ -A ]

 [ -c | -s ]

 [ -d dir [ -N ] ]

 [ [ -D date | -r rev ] -f ]

 [ -j rev1 [ -j rev2 ] ]

 [ -k kflag ]

 [ -l | -R ]

 [ -n ]

 [ -p ]

 [ -P ]

 module ...

Copy files from the repository to the sandbox.

The standard meanings of the common client options -D, -f, -k, -l, -n, -r, and -R apply. Additional options are:

-A

Reset any sticky tags or dates.

-c

Copy the module file to standard output.

-d dir

Override the default directory name.

-j rev

Join branches together.

-N

Don't shorten module paths.

-p

Pipe the files to standard output, with header lines between them showing the filename, RCS filename, and version.

-P

Prune empty directories.

-s

Show status for each module from the modules file.

commit
commit

 [ -f | [ -l | -R ] ]

 [ -F file | -m message ]

 [ -n ]

 [ -r revision ]

 [ file ... ]

Commit the changes (if any) made to the specified files in the sandbox to the repository. If no files are specified, commit all modified files.

The standard meanings of the common client options -l, -n, -r, and -R apply. Use of the -r option causes the revision to be sticky, requiring the use of admin -A to continue to use the sandbox. Additional options are:

-f

Force commit, even if no changes were made.

-F file

Use the contents of the file as the message.

-m message

Use the message specified.

diff
diff

 [ -k kflag ]

 [ -l | -R ]  [ format ]

 [ [ -r rev1 | -D date1 ] [ -r rev2 | -D date2 ] ]

 [ file ... ]

Compare two versions of a file and display the differences in a format determined by the options. By default, the sandbox version of the file is compared to the repository version it was originally copied from.

The standard meanings of the common client options -D, -k, -l, -r, and -R apply. All options for the diff command can also be used.

edit
edit

 [ -a action ]

 [ -l | -R ]

 [ file ... ]

The edit command is used in conjunction with watch to permit a more coordinated (serialized) development process. It makes the file writable and sends out an advisory to any users that have requested them. A temporary watch is established and will be removed automatically when either the unedit or the commit command is issued.

The standard meanings of the common client options -l and -R apply. The only additional option that can be used with the edit command is -a actions. This option is used to specify the actions to watch. The legal values for actions are described in the entry for the watch command.

editors
editors

 [ -l | -R ]

 [ file ... ]

Display a list of users working on the files specified. This is determined by checking which users have run the edit command on those files. If the edit command has not been used, no results are displayed.

The standard meanings of the common client options -l and -R apply.

See also watch.

export
export

 [ -d dir [ -N ] ]

 [ -D date | -r rev ]

 [ -f ]  [ -k kflag ]

 [ -l | -R ]

 [ -n ]

 [ -P ]

 module ...

Export files from the repository, much like the checkout command, except that the result is not a sandbox (i.e., CVS subdirectories are not created). This can be used to prepare a directory for distribution. For example:

$ cvs export -r foo-1_0 -d foo-1.0 foo

$ tar czf foo-1.0.tar.gz foo-1.0

The standard meanings of the common client options -D, -f, -k, -l, -n, -r, and -R apply. Additional options are:

-d dir

Use dir as the directory name instead of using the module name.

-n

Don't run any checkout programs.

-N

Don't shorten paths.

When checking out a single file located one or more directories down in a module's directory structure, the -N option can be used with -d to prevent the creation of intermediate directories.

help
help

Display helpful information about using the cvs program.

history
history

 [ -a | -u user ]

 [ -b string ]

 [ -c ]

 [ -D date ]

 [ -e | -x type ]

 [ -f file | -m module | -n module | -p repository ]...

 [ -l ]

 [ -o ]

 [ -r rev ]

 [ -t tag ]

 [ -T ]

 [ -w ]

 [ -x types ]

 [ -z zone ]

 [ file ... ]

Display historical information. To use the history command, you must first set up the history file in the repository. See Section 15.5.3 for more information on this file.

When used with the history command, the functions of -f, -l, -n, and -p are not the same as elsewhere in CVS.

The standard meanings of the common client options -D and -r apply. History is reported for activity subsequent to the date or revision indicated. Additional options are:

-a

Show history for all users (default is current user).

-b str

Show history back to the first record containing str in the module name, filename, or repository path.

-c

Report each commit.

-e

Report everything.

-f file

Show the most recent event for file.

-l

Show last event only.

-m module

Produce a full report on module.

-n module

Report the last event for module.

-o

Report on modules that have been checked out.

-p repository

Show history for a particular repository directory.

-t tag

Show history since tag was last added to the history file.

-T

Report on all tags.

-u name

Show history for a particular user.

-w

Show history only for the current working directory.

-x types

Report on specific types of activity. See Table 15-19.

-z zone

Display times according to the specified time zone.

The -p option should limit the history report to entries for the directory or directories (if multiple -p options are specified) given, but as of Version 1.10.8, it doesn't seem to affect the output. For example, to report history for the CVSROOT and hello modules, run the command:

cvs history -p CVSROOT -p hello

Using -t is faster than using -r because it only needs to search through the history file, not all of the RCS files.

The record types shown in Table 15-19 are generated by update commands.

Table 15-19. Update-related history record types

Type

Description

C

Merge was necessary, but conflicts requiring manual intervention occurred.

G

Successful automatic merge.

U

Working file copied from repository.

W

Working copy deleted.

The record types shown in Table 15-20 are generated by commit commands.

Table 15-20. Commit-related history record types

Type

Description

A

Added for the first time

M

Modified

R

Removed

Each of the record types shown in Table 15-21 is generated by a different command.

Table 15-21. Other history record types

Type

Command

E

export

F

release

O

checkout

T

rtag

import
import

 [ -b branch ]

 [ -d ]

 [ -I pattern ]

 [ -k kflag ]

 [ -m message ]

 [ -W spec ]

 module

 vendor_tag

 release_tag ...

Import an entire directory into the repository as a new module. Used to incorporate code from outside sources or other code that was initially created outside the control of the CVS repository. More than one release_tag may be specified, in which case multiple symbolic tags will be created for the initial revision.

The vendor_tag argument is used to track third-party code that may be used in your project. By using different values for this argument, you can track the third-party code separately, and upgrade that portion of your code to a new release with a subsequent cvs import command. Since the argument is not optional, use some conventional value such as "vendor" whenever the code being imported should not be tracked separately.

The release_tag argument is used to associate a symbolic tag with the initial version of every file being imported. Since this argument is not optional, use some conventional value such as "start" whenever you don't have a more meaningful value to provide.

The standard meaning of the common client option -k applies. Additional options are:

-b branch

Import to a vendor branch.

-d

Use the modification date and time of the file instead of the current date and time as the import date and time. For local repository locators only.

-I pattern

Filename patterns for files to ignore.

-m message

Use message as the log message instead of invoking the editor.

-W spec

Wrapper specification.

The -k setting applies only to files imported during this execution of the command. The keyword substitution modes of files already in the repository are not modified.

When used with -W, the spec variable is in the same format as entries in the cvswrappers administrative file (see Section 15.5.3.6).

Table 15-22 describes the status codes displayed by the import command.

Table 15-22. import status codes

Status

Description

C

Changed. The file is in the repository, and the sandbox version is different; a merge is required.

I

Ignored. The .cvsignore file is causing CVS to ignore the file.

L

Link. Symbolic links are ignored by CVS.

N

New. The file is new; it has been added to the repository.

U

Update. The file is in the repository, and the sandbox version is not different.

log
log

 [ -b ]

 [ -d dates ]

 [ -h ]

 [ -N ]

 [ -rrevisions ]

 [ -R ]

 [ -s states ]

 [ -t ]

 [ -wlogins ]

 [ file ... ]

Print an activity log for the files.

The standard meaning of the common client option -l applies. Additional options are:

-b

List revisions on default branch.

-d dates

Report on these dates.

-h

Print header only.

-N

Don't print tags.

-r[revisions]

Report on the listed revisions. There is no space between -r and its argument. Without an argument, the latest revision of the default branch is used.

-R

Print RCS filename only. The usage of -R here is different from elsewhere in CVS (-R usually causes CVS to operate recursively).

-s states

Print only those revisions having one of the specified states.

-S

Don't print the header if the output would otherwise be empty.

-t

Print only header and descriptive text.

-wlogins

Report on checkins by the listed logins. There is no space between -w and its argument.

For -d, use the date specifications in Table 15-23. Multiple specifications separated by semicolons may be provided. For -s, separate multiple states with commas.

Table 15-23. log date range specifications

Specification

Description

d1<d2 or d2>d1

The revisions dated between d1 and d2, exclusive

d1<=d2 or d2>=d1

The revisions dated between d1 and d2, inclusive

<d or d>

The revisions dated before d

<=d or d>=

The revisions dated on or before d

d< or >d

The revisions dated after d

d<= or >=d

The revisions dated on or after d

d

The most recent revision dated d or earlier

For -r, use the revision specifications in Table 15-24.

Table 15-24. log revision specifications

Specification

Description

rev1: rev2

The revisions between rev1 and rev2, inclusive.

:rev

The revisions from the beginning of the branch to rev, inclusive.

rev:

The revisions from rev to the end of the branch, inclusive.

branch

All revisions on the branch.

branch1: branch2

All revisions on all branches between branch1 and branch2, inclusive.

branch.

The latest revision on the branch.

For rev1:rev2, it is an error if the revisions are not on the same branch.

login
login

Log into a remote repository. The password entered will be cached in the ~/.cvspass file, since a connection to the server is not maintained across invocations.

logout
logout

Log out of a remote repository. The password cached in the ~/.cvspass file will be deleted.

rannotate
rannotate

 [ [ -D date | -r rev ] -f ]

 [ -F ]

 [ -l | -R ]

 module ...

CVS prints a report showing each line of the specified module or module file. Each line is prefixed by information about the most recent change to the line, including the revision number, user, and date. If no revision is specified, the head of the trunk is used.

The rannotate command differs from the annotate command in that it refers directly to modules (and their files) in the repository rather than inferring the module based on the sandbox from which it is run. The first path component of each module argument must be a valid module for the repository.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply. There is one additonal option:

-F

Annotate binary files. CVS normally skips binary files.

rdiff
rdiff

 [ -c | -s | -u ]

 [ { { -D date1 | -r rev1 } [ -D date2 | -r rev2 ] } | -t ]

 [ -f ]

 [ -l | -R ]

 [-V vn]

 file ...

Create a patch file that can be used to convert a directory containing one release into a different release.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply. Additional options are:

-c

Use context diff format (the default).

-s

Output a summary of changed files instead of a patch file.

-t

Show the differences between the two most recent revisions.

-u

Use unidiff format.

-V rcsver

Obsolete. Used to specify version of RCS to emulate for keyword expansion. (Keyword expansion emulates RCS Version 5.)

release
release

  [ -d ]

  directory ...

Sandboxes can be abandoned or deleted without using cvs release, but using the release command will log an entry to the history file (if this mechanism is configured) about the sandbox being destroyed. In addition, it will check the disposition (recursively) of each sandbox file before deleting anything. This can prevent destroying work that has not yet been committed.

There is only one option that can be used with the release command, -d. The -d option will delete the sandbox copy if no uncommitted changes are present.

New directories (including any files in them) in the sandbox will be deleted if the -d option is used with release.

The status codes listed in Table 15-25 are used to describe the disposition of each file encountered in the repository and the sandbox.

Table 15-25. release status Codes

Status

Description

A

The sandbox file has been added (the file was created and cvs add was run), but the addition has not been committed.

M

The sandbox copy of the file has been modified.

P

U

Update available. There is a newer version of the file in the repository, and the copy in the sandbox has not been modified.

R

The sandbox copy was removed (the file was deleted and cvs remove was run), but the removal was not committed.

?

The file is present in the sandbox but not in the repository.

remove
remove

  [ -f ]

  [ -l | -R ]

  [ file ... ]

Indicate that files should be removed from the repository. The files will not actually be removed until they are committed. Use cvs add to resurrect files that have been removed if you change your mind later.

The standard meanings of the common client options -l and -R apply. Only one other option may be used with the remove command, -f. When used, -f will delete the file from the sandbox first.

rlog
rlog

  [ -b ]

  [ -d dates ]

  [ -h ]  [ -N ]  [ -rrevisions ]

  [ -R ]

  [ -s state ]

  [ -t ]

  [ -wlogins ]

  [ module ... ]

Print an activity log for the modules.

The standard meaning of the common client option -l applies. Additional options are:

-b

List revisions on default branch.

-d dates

Report on these dates.

-h

Print header only.

-N

Don't print tags.

-r[revisions]

Report on the listed revisions. There is no space between -r and its argument. Without an argument, the latest revision of the default branch is used.

-R

Print RCS filename only. The usage of -R here is different from elsewhere in CVS (-R usually causes CVS to operate recursively).

-s state

Print only those revisions having the specified state.

-t

Print only header and descriptive text.

-wlogins

Report on checkins by the listed logins. There is no space between -w and its argument.

For -d, use the date specifications in Table 15-23. Multiple specifications separated by semicolons may be provided.

For -r, use the revision specifications in Table 15-24.

rtag
rtag

  [ -a ]

  [ -b ]

  [ -B ]

  [ -d ]

  [ -D date | -r rev ]

  [ -f ]

  [ -F ]

  [ -l | - R ]

  [ -n ]

  tag

  file ...

Assign a tag to a particular revision of a set of files. If the file already uses the tag for a different revision, cvs rtag will complain unless the -F option is used. This command does not refer to the sandbox file revisions (use cvs tag for that), so it can be run outside of a sandbox if desired.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply. Additional options are:

-a

Search the attic for removed files containing the tag.

-b

Make it a branch tag.

-B

Allow movement or deletion of branch tags (used with -d or -F.)

-d

Delete the tag.

-F

Force. Move the tag from its current revision to the one specified.

-n

Don't run any tag program from the modules file.

status
status

  [ -l | -R ]

  [ -v ]

  [ file ... ]

Display the status of the files.

The standard meanings of the common client options -l and -R apply. You can use status -v to include tag information.

tag
tag

  [ -b ]

  [ -c ]

  [ -d ]

  [ -D date | -r rev ]

  [ -f ]

  [ -F ]

  [ -l | R ]

  tag

  [ file ... ]

Assign a tag to the sandbox revisions of a set of files. You can use the status -v command to list the existing tags for a file.

The tag must start with a letter and consist entirely of letters, numbers, dashes, and underscores. Therefore, while you might want to tag your hello project with 1.0 when you release Version 1.0, you'll need to tag it with something like hello-1_0 instead.

The standard meanings of the common client options -D, -f, -l, -r, and -R apply. Additional options are:

-b

Make a branch.

-c

Check for changes. Make sure the files are not locally modified before tagging.

-d

Delete the tag.

-F

Force. Move the tag from its current revision to the one specified.

Since the -d option throws away information that might be important, it is recommended that you use it only when absolutely necessary. It is usually better to create a different tag with a similar name.

unedit
unedit

  [ -l | -R ]

  [ file ... ]

Abandon file modifications and make the file read-only again. Watchers will be notified.

The standard meanings of the common client options -l and -R apply.

update
update

  [ -A ]

  [ -C ]

  [ -d ]

  [ -D date | -r rev ]

  [ -f ]

  [ -I pattern ]

  [ -j rev1 [ -j rev2 ] ]

  [ -k kflag ]

  [ -l | -R ]

  [ -p ]

  [ -P ]

  [ -W spec ]

  [ file ... ]

Update the sandbox, merging in any changes from the repository. For example:

cvs -n -q update -AdP

can be used to do a quick status check of the current sandbox versus the head of the trunk of development.

The standard meanings of the common client options -D, -f, -k, -l, -r, and -R apply. Additional options are:

-A

Reset sticky tags.

-C

Replace modified files with clean copies.

-d

Create and update new directories.

-I pattern

Provide filename patterns for files to ignore.

-j revision

Merge in (join) changes between two revisions.

-p

Check out files to standard output.

-P

Prune empty directories.

-W spec

Provide wrapper specification.

When using -C, CVS makes backups of modified files before copying the clean version. The backup files are named .#file.revision.

Using -D or -r results in sticky dates or tags, respectively, on the affected files (using -p along with these prevents stickiness). Use -A to reset any sticky tags or dates.

If two -j specifications are made, the differences between them are computed and applied to the current file. If only one is given, then the common ancestor of the sandbox revision and the specified revision is used as a basis for computing differences to be merged. For example, suppose a project has an experimental branch, and important changes to the file foo.c were introduced between revisions 1.2.2.1 and 1.2.2.2. Once those changes have proven stable, you want them reflected in the main line of development. From a sandbox with the head revisions checked out, run:

$ cvs update -j 1.2.2.1 -j 1.2.2.2 foo.c

CVS finds the differences between the two revisions and applies those differences to the file in your sandbox.

The spec used with -W is in the same format as entries in the cvswrappers administrative file (see Section 15.5.3.6).

The status codes listed in Table 15-26 are used to describe the action taken on each file encountered in the repository and the sandbox.

Table 15-26. update status codes

Status

Description

A

Added. Server took no action because there was no repository file. Indicates that cvs add, but not cvs commit, has been run.

C

Conflict. Sandbox copy is modified (it has been edited since it was checked out or last committed). There was a new revision in the repository, and there were conflicts when CVS merged its changes into the sandbox version.

M

Modified. Sandbox copy is modified (it has been edited since it was checked out or last committed). If there was a new revision in the repository, its changes were successfully merged into the file (no conflicts).

P

Patched. Same as U, but indicates the server used a patch.

R

Removed. Server took no action. Indicates that cvs remove, but not cvs commit, has been run.

U

Updated. The file was brought up to date.

?

File is present in sandbox but not in repository.

version
version

Display the version of the CVS client (and server, if appropriate) being used.

watch
watch

  { { on | off } | { add | remove } [ -a action ] }

  [ -l | -R ]

  file ...

The watch command controls CVS's edit tracking mechanism. By default, CVS operates in its concurrent development mode, allowing any user to edit any file at any time. CVS includes this watch mechanism to support developers who would rather be notified of edits made by others proactively than discover them when doing an update. The CVSROOT/notify file determines how notifications are performed.

Table 15-27 shows the watch subcommands and their uses.

Table 15-27. watch subcommands

Subcommand

Description

add

Start watching files.

off

Turn off watching.

on

Turn on watching.

remove

Stop watching files.

The standard meanings of the common client options -l and -R apply. The only other option that can be used with the watch command is -a action. The -a option is used in conjunction with one of the actions listed in Table 15-28.

Table 15-28. watch Actions

Action

Description

all

All of the following.

commit

A user has committed changes.

edit

A user ran cvs edit.

none

Don't watch. Used by the edit command.

unedit

A user ran cvs unedit, cvs release, or deleted the file and ran cvs update, re-creating it.

See also edit, editors, unedit, and watchers.

watchers
watchers

  [ -l | -R ]

  [ file ... ]

Display a list of users watching the specified files. This is determined by checking which users have run the watch command on a particular file (or set of files). If the watch command has not been used, no results will be displayed.

The standard meanings of the common client options -l and -R apply.

See also watch.


Chapter 16. Graphical Desktop Overview

Linux was criticized in the past for lacking an easy-to-use graphical desktop, but that has changed significantly. These days, there are several such desktops, as well as advanced alternatives aimed at experts, developers, and high-performance enthusiasts. This book covers three graphical configurations: two complete environments with their own application suites (GNOME in Chapter 17 and KDE in Chapter 18), and one traditional window manager (fvwm2 in Chapter 19).

GNOME and KDE are the most commonly used desktops on Linux systems. KDE has been around longer, and as the default desktop for SuSE, has more of a European following. The GNOME project was started more recently, and its desktop, used as the default for Red Hat Linux, is more common in the United States. Many operating system vendors have produced unified themes for the two desktops, so that applications written with one toolkit appear consistent with those from the other.


16.1 Desktop Environments and Window Managers

The simplest graphical desktops consist of the X Window System, which displays the windows and graphics, and a window manager, which determines where windows are placed and how users interact with applications. A window manager, such as fvwm2, determines window "focus" (that is, which window is currently accepting input) and some keyboard shortcuts. Window managers often include some sort of control panel or task bar, but not always.

A desktop environment, in contrast, attempts to provide a complete experience, offering many of the tools someone would need for a typical day at the office. A desktop environment also includes more extensive cooperation between applications, ensuring that cutting and pasting text and dragging and dropping objects around the desktop work as expected, even between applications. A minimal installation would include a window manager with control panel, a file manager, and a few sample applications such as a text editor. Additional items such as games, email, calendars, office tools, and software development tools are usually available and work closely with the desktop core.

Both GNOME and KDE should look familiar to Windows and Macintosh users: they feature a desktop background with icons for files and folders, a bar with buttons and a clock at the top or bottom of the screen, and a central menu to access everything from applications to system settings. Both have more settings available than either Windows or the Macintosh OS, including support for virtual desktops, customizable key bindings, and window focus behavior. They also include or share a series of applications: office suites for word processing, spreadsheets, and presentations; groupware tools for email, calendar, and address-book management; and image processing, web, and software development tools for artists, programmers, and system administrators.

While GNOME and KDE offer entire suites of applications and configuration tools and serve as both software and software development platform, fvwm2 focuses strictly on handling windows and the desktop background. fvwm2 does not include other applications, and is customized with configuration files the way that all Linux and Unix applications used to be. It is, in fact, almost endlessly customizable—as long as you are willing to edit the right files. Some developers of software for GNOME or KDE will admit to using fvwm2 or another window manager on their own systems, because they have customized it to work exactly as they wish.


16.2 Desktop Differences: Development

The differences between KDE and GNOME matter more to developers than to the average user. If you choose to develop software based on one of these platforms, your choice of toolkit and desktop environment will probably be based on two factors: language and license. The GNOME libraries (the main widget set is called Gtk+) are written in C, and the KDE libraries (notably Qt) in C++. For both desktops, bindings for other languages, such as Perl, Python, and Java, are available and popular, so the choice comes down to the architecture you prefer.

Licensing is slightly more complicated. Qt, the base toolkit for KDE software, is controlled by TrollTech, Inc., and is available under a dual licensing scheme: free for the development of open software, and proprietary for the development of proprietary software. Most GNOME libraries are available for open or proprietary development at no charge. Visit http://developer.gnome.org and http://developer.kde.org for more details on building software with these tools.


Chapter 17. GNOME

One of the two popular desktop environments used with Linux, GNOME is provided as the default desktop for Red Hat, Debian, and several other popular distributions. As a graphical environment, GNOME provides users with a highly customizable user interface and consistent functionality of common GUI features such as menus, toolbars, and buttons. In addition, it offers users a growing set of native applications to create a productive computing system. The number and quality of applications are a testament to the developer-friendly GNOME libraries; many GNOME technologies are also used in nongraphical or totally unrelated software. GNOME is distributed with most Linux distributions, and you can also get it from the GNOME web site (http://www.gnome.org) or from Ximian (http://www.ximian.com), a company that specializes in the GNOME desktop.

GNOME stands for "GNU Network Object Model Environment," and although the name is admittedly obscure, it does point to one of GNOME's core technologies: its CORBA-based objects. CORBA (Common Object Request Broker Architecture) specifies methods that allow interaction among applications through the sharing and embedding of component objects. For example, a spreadsheet created by Gnumeric (a GNOME spreadsheet program) can be placed as an object into an AbiWord document, and the Nautilus file browser can display images, web pages, and so forth by embedding an image viewer and HTML display engine. GNOME uses two libraries to do this: ORBit, (http://orbit-resource.sourceforge.net), which provides an Object Request Broker (ORB), and Bonobo (http://developer.ximian.com/articles/whitepapers/bonobo), which is designed to simplify the task of creating reusable software components and compound documents.

This edition of Linux in a Nutshell covers a GNOME desktop based on the GNOME 2 platform, which is included in Red Hat 8.0, Mandrake 9.0, and SuSE 8.1, among other distributions. The new platform differs from the previous version, GNOME 1.4, in a number of significant ways. Overall, the new platform has brought increased performance and stability, more coherent and powerful developer tools, and a friendlier, simpler interface.

You do not need to be familiar with earlier versions of GNOME to use GNOME 2. If you are familiar with earlier versions and want to know what's new, or if you are curious about the history of the project, see Section 17.5 at the end of this chapter for additional background information.


17.1 Desktop Overview

Figure 17-1 shows the default GNOME desktop. The left side of the screen contains icons that are shortcuts to open applications, files, or URLs. The top icon is a link to the user's home folder; when double-clicked, it launches the Nautilus file manager to display the folder's contents. The other icons include shortcuts to the floppy drive and CD-ROM and links to web pages. In general, double-clicking on an icon leads to the most logical operation, so clicking folder icons displays folder contents, clicking application icons launches applications, and clicking a file opens the file in its most appropriate application (see Section 17.4.4.2 for information on how to choose which one). A button or icon you can press to start an application is called a launcher. You can drag and drop the icons around the desktop to arrange them as you like, or drag them onto the Trash icon to get them out of your way.

Figure 17-1. The GNOME desktop

You can also right-click on any blank space in the desktop and get a context menu that allows you to:

  • Open a new file manager window.

  • Create a new folder.

  • Create an application launcher.

  • Open a new terminal window.

  • Run scripts or executable files you place in your scripts folder (~/.gnome2/nautilus-scripts).

  • Clean up the icons on the desktop.

  • Copy, paste, or cut selected files.

  • Change your desktop background.

  • Display the contents of any mounted disk in the file manager.

The bars across the top and bottom of the screen are called panels. Some distributions and configurations use only one, and others use more than two. GNOME allows you to create a variety of panels and choose their placement, size, and behavior. The one at the top, called the menu panel, is perhaps the most common and important. It may be slightly different in some distributions of GNOME, but it generally consists of two menus on the left, and a clock and application switcher on the right. Some systems may also include other small applications, called applets; see Section 17.2.3 for more information.

If you do not have a menu panel, the desktop probably offers the GNOME menu, which is similar to the Start menu in Microsoft Windows. On most systems, it appears in the lower left corner and is designated with a GNOME foot logo, earning it the nickname "the foot menu." In Red Hat 8.0, click the red hat to get the same menu with a list of applications, help, and a few other tools, plus the logout and screen-locking tools. If you want to add this GNOME menu to a panel, right-click on any blank space in the panel and select Add to Panel [image] GNOME Menu.

In general, the panel is a primary means of finding and opening applications and managing your desktop. You can add buttons to the panel to launch any application on your system; you can also include small applications, called applets, in the panel. For more information, see Section 17.2.

GNOME allows you an enormous number of configuration options for your desktop environment. You can right-click on just about anything and get a pop-up menu (called a context menu) containing specific actions for that item and a way to configure its properties. General configuration settings are contained in the GNOME Control Center. You can access this tool by selecting System and then Settings in your menu panel (on some systems, look for Desktop Preferences under the Programs or Applications menu). For more information about settings, see Section 17.4.

17.1.1 Adding Desktop Icons

Desktop icons offer convenient double-click access to your most important files, applications, and links. The items displayed on your desktop exist as files in the .gnome-desktop directory of your home directory. Anything you add to that directory will appear on the desktop.

To add an icon that launches an application, select New Launcher. This opens the Desktop Entry Properties dialog box as shown in Figure 17-2. Provide the name of the launcher (this will be the text displayed underneath the icon), a comment (the tooltip that appears when the pointer is over the icon), and the command used to run the application. After you click OK, the new launcher icon appears on your desktop.

Figure 17-2. Desktop entry properties

A convenient use of desktop icons is to provide shortcuts to frequently used files or folders. Adding shortcuts is easiest from the file manager (Nautilus). Display the directory containing the item for which you want a shortcut on your desktop, right-click on the item, and select Make Link. Then click on the new link and drag it to the desktop, which has the underlying effect of moving it to your ~/.gnome-desktop folder. You can copy an item instead of moving it by pressing the Ctrl key while selecting and dragging the item.


17.2 The Panel

The GNOME panel can contain several different types of objects. The most obvious are the buttons for the menu and application launchers. You also can use a button to open a drawer, which is a subpanel containing additional launchers. There are a few special types of buttons used for logging out of the session and locking the screen. Finally, small programs called applets can be run on the panel. The Workspace Switcher, the Window List, and the clock are examples of panel applets.

As with many other things in GNOME, you can find settings for the panel by looking in the Panel menu under the GNOME menu, or by right-clicking on the panel itself. In both cases, there are options to add new launchers or applets to the panel; to adjust the style, size, and display of the panel; or to create new panels on the desktop. The menu panel does not have a properties dialog, as it is preconfigured. If you wish, you can remove it or replace it with an edge panel that is more to your liking.

17.2.1 Additional Panels

You can create more than one panel on your desktop. This is useful if you have different sets of applications used for specific but common tasks. For example, if you do a lot of work on graphics, you can dedicate a panel to launch your favorite graphics tools. To create a new panel, right-click on the default panel and select Add New Panel, or, from the GNOME menu, select Panel [image] Add New Panel. There are five different types of panels available from the submenu:

Edge panel

The style of the default panel. It stretches across one entire edge of the screen. Arrow buttons on each end of the panel are used to collapse the panel to the side of the screen. Clicking on the remaining visible arrow button of a collapsed panel will cause the panel to appear again in full.

Corner panel

A panel that is anchored to one corner of the screen and extends just enough to fit the buttons and applets it contains. A corner panel can be hidden by clicking the arrow button that is at the edge of the screen. The arrow button farthest from the edge will anchor an aligned panel on the opposite side of the screen.

Sliding panel

Like a corner panel, except that instead of being anchored to a corner, it can be placed anywhere along the edge of the screen. This is similar to the Dock in Macintosh OS X.

Floating panel

A panel that can be placed anywhere on the screen.

Menu panel

A special type of preconfigured edge panel. It is a thin bar that stretches across the top of the screen and contains drop-down menus and a clock. Users of the Macintosh will find it quite familiar.

All of the panels except the menu panel can be moved by middle-clicking (or clicking the left and right buttons simultaneously) and dragging the panel to another part of the screen. They can also be configured individually from the Panel menu in its context (right-click) menu. Right-click and select Panel [image] Properties to open a properties dialog. Your options vary depending on panel type, but the complete list is:

Position

This option does not appear for floating panels. For other types, choose a position by clicking the location on a diagram of a screen. You can also move all four configurable types of panels without this dialog by middle-clicking and dragging to a new location.

Orientation

This option is available only for floating panels. It lets you choose whether the panel should be vertical or horizontal. Other panels are aligned with the screen edges.

Autohide

Check this box to have the panel hide itself automatically. A small amount of the panel will be left showing; bring the mouse pointer over that bit, and the panel will reappear. This functions similarly to the Microsoft Windows task bar.

Show Hide Buttons, Arrows on Hide Buttons

At each end of the panel is a hide button with an arrow. Click the button, and the panel shrinks into it. Click again, and the panel reappears. Uncheck these boxes to get rid of the buttons or to remove the arrow labels from them. The buttons are slightly smaller if they are unlabeled.

A second tab of the preferences window allows you to choose a background for your panel. Normally, a panel is light gray, but you can choose a color or even an image to go behind your buttons. If you choose an image, you can also scale or stretch it to fit the panel more accurately.

17.2.2 Adding an Application Launcher to the Panel

One of the conveniences of the panel is creating launcher icons that allow you one-click access to frequently used applications. To add an application, right-click the panel and select Add to Panel [image] New Launcher. You can also right-click launchers in your menus and choose Add This Launcher to Panel, or simply drag launchers to the panel.

To customize the launcher, right-click on it and select Properties. Here, you can enter a name for the application, a comment to be used as a tooltip, and the command used to open the application. (This is similar to creating a launcher, as shown in Section 17.1.1.) Click on the icon button to select the image to be used for the button on the panel. If the application is to be run in a terminal window—that is, if it is a text-based program normally invoked from the shell—check the box labeled Run in Terminal.

Launcher buttons can be placed in any position and order you want on the panel. To move a launcher button, right-click it and select Move, or middle-click and drag it. The mouse pointer will change shape, indicating that you can drag the button to another position. Click to set the new position of the button.

The middle mouse button has two features that are often overlooked. First, it can be used to paste whatever text is currently selected, without a copy command. Second, it can be used to move items such as the Workspace Switcher Applet that cannot be moved with the left mouse button. (In the Workspace Switcher Applet, left clicking and dragging moves individual windows among the workspaces, rather than moving the applet itself.)

17.2.3 GNOME Panel Applets

As mentioned earlier, GNOME offers small applications that run inside the panel, called panel applets. Some will already be in your panel by default. To add more, right-click on a blank space in the panel and select one of the items under Add to Panel [image] Applet. The two most important GNOME panel applets are the Workspace Switcher Applet and the Window List Applet.

17.2.3.1 Workspaces and the Workspace Switcher

GNOME allows you to create extra screen real estate by multiplying your desktop with workspaces. You can keep a few windows open in each workspace instead of choosing between clutter and closing windows. For example, you might keep your mail program open in one workspace with a few messages open in separate windows, then have one or two browser windows open in a second workspace, and a spreadsheet in a third.

The workspaces are drawn in miniature on your panel in the Workspace Switcher Applet, which at first looks like a series of small grey boxes. Drawn inside each workspace, you can see the individual windows you have open, and even drag them from one workspace to another with the left mouse button. You can navigate these workspaces with the keyboard shortcuts Ctrl+Alt+Left, Ctrl+Alt+Right, Ctrl+Alt+Up, and Ctrl+Alt+Down, or by clicking one of the workspaces in the Workspace Switcher Applet.

Most systems give you four workspaces by default, although some stick with one or two. To create more, open the Workspace Switcher Applet preferences tool by right-clicking on the Workspace Switcher Applet and selecting Preferences. There, you can select not only the number of workspaces, but also their names and their layout in columns and rows.

17.2.3.2 The Window List Applet

The Window List Applet applet lets you keep track of open windows. It displays a button on the panel for each window you have open. Clicking on a button in the tasklist will bring that window to the foreground, reopening it if it was minimized.

You can right-click on any of the buttons for an application to get a context menu that allows you to interact with the window for that application, and close, minimize, maximize, un-maximize, move, or resize it.

To set the way the Window List Applet behaves, right-click on an empty space in the window list or on the small "handle" on its left side, and select Preferences. This will open a dialog box that allows you to set the following options:

Window List content

You can show the windows from all your workspaces, or just from the workspace you are currently in.

When restoring minimized windows

This setting matters only if you choose to display windows from all your workspaces. The default setting, "Restore to current workspace," means that minimized windows you restore with the Window List Applet will appear on your current workspace. If you select "Restore to native workspace," the windows will appear in the workspace where you were last using them. In other words, you can choose to have your windows appear either where you are now or where you were last using them.

Window grouping

One of the more useful Window List Applet features is window grouping. If you have several windows open for a particular application, the Window List Applet can save space by combining all the entries for that application. Then, instead of a button for each window, you'll have a menu for the whole application. For example, if you have one Galeon web browser window open, you will have a button that shows the Galeon icon and the title of the page for that window. If you have five open, the Window List Applet will show "Galeon (5)," and clicking the button will offer you a choice of which window to focus. You can set the applet never to group windows, to group windows only when it runs out of space, or to group windows whenever it can.

Window List size

Choose a minimum and maximum size for your window list applet. The applet will grow between these sizes depending upon how many windows you have open.

17.2.3.3 Miscellaneous applets

In addition to the Window List and Workspace Switcher Applets, there are roughly a dozen other applets in five categories. You can find the complete list of applets by right-clicking on the panel and selecting Add to Panel [image] Applet.

Accessories

A clock, a dictionary, a stock ticker, and a weather report.

Amusements

A fish that tells your fortune, and some googly eyes that follow your mouse pointer.

Internet

A modem traffic monitor and a mail checker.

Multimedia

A CD player and volume control.

Utility

The largest category: a battery charge monitor, international character and keyboard layout tools, a mini command line, a system load monitor, a system event notification area, and the Workspace Switcher and Window List Applets.


17.3 The GNOME Menu and the Menu Panel Menus

Because different distributions organize their menus differently, you're best off exploring them yourself or referring to the documentation for your particular system. For the most part, however, the menus have similar contents: applications, help files, settings or preferences tools, utilities and system administration tools, and a few special items like Log Out and Run Command. The major difference is whether these items are split into several menus, as in the menu panel, or put in a single place, as in the GNOME menu.

There are, however, a number of common tasks related to menu items that do not vary across distributions, and we'll describe those here. First, there are context menus for individual menu items. To see them, right-click on a menu item (this is easier if you do not keep the left mouse button pressed while navigating your menus). The possible actions are:

Add this launcher to panel

Add the item as a launcher in the panel. If you have more than one panel, the launcher will be added to the first panel. You can then drag the launcher to wherever you actually want it.

Put into run dialog

Display this item as a shortcut in the Run Program dialog.

Entire menu

The two items here, "Add this as menu to panel" and "Add this as drawer to panel," allow you to add the entire submenu containing the launcher to your panel as either a drawer (a portion of panel that stays open when a menu might close) or as a menu.

The menu customization tools are one of the simplest and most obvious improvements in the GNOME 2 platform. To alter your menus, just open your Nautilus file manager and type "applications:///" into the location bar. The Applications display represents your menus and submenus as folders, with item launchers in them. Drag items around and move, copy, delete, or rename them as you see fit.

To add a submenu, right-click in an empty spot in the folder and select New Folder, then rename the folder, or right-click on it to set its name and icon.

To add a launcher, right-click in an empty spot in the folder and select New Launcher, then enter the name of the application, type in any pop-up text you want to describe it, and enter or browse for the command that starts the application itself. If you're not sure where that is, look in the /usr/bin directory, or use the which or locate commands (see Chapter 2) to find it.


17.4 The GNOME Control Center

The GNOME Control Center (Figure 17-3) is where most customization and configuration of your desktop environment takes place. There are several ways to open it: you can click the toolbox button on your panel, select items in the Preferences section of the GNOME menu, or choose Settings in the System menu. The Control Center is also one place where different distributions vary significantly. The tools covered in this section appear in most distributions, but you may find a slightly different set that is organized in a different fashion.

Figure 17-3. GNOME Control Center

17.4.1 Personal Settings

These settings control the system information pertaining most directly to you.

17.4.1.1 Accessibility

The Accessibility tool, new in GNOME 2, handles the various settings related to making a computer easier to use for people with disabilities.

There are three sections to the tool: Basic, Filters, and Mouse, plus the option to turn all the accessibility options on or off at once. To set any option, you must first click the "Enable keyboard accessibility" checkbox.

In the Basic section, you can set the following options:

Features

You can set the features to turn off automatically if they are unused, or to emit a keyboard beep when turned on or off. This helps prevent confusion if they are turned on accidentally.

The Import Feature Settings button is relevant only to those migrating from CDE to GNOME 2, and allows you to import CDE accessibility settings.

Sticky Keys

Sticky Keys allows you to press key combinations such as Ctrl+R by pressing only one key at a time. If you choose to enable the sticky keys feature, you can also set it to beep when used, and to turn off if a normal key combination is pressed.

Repeat Keys

Key repeat can be troublesome for people with limited mobility. To turn it off, uncheck this box. Alternately, you can use the sliders to adjust the delay before key repeating begins, and the speed at which keys are repeated.

The Filters section handles the way that the system can ignore accidental keypresses. Individuals with limited dexterity may wish to use these features to prevent extraneous key inputs.

Slow Keys

Check the Enable Slow Keys button to have the system accept only keys that are held down, and ignore keys that are tapped quickly. You can set an amount of time before a keypress is registered, and also set beeps for keypress, key acceptance, or key rejection.

Bounce Keys

The Bounce Keys feature ignores duplicate keypresses: if you hit a key and then accidentally hit it again, the system will ignore the second input. You can set the amount of time the system will wait before accepting another key, and have it beep when it rejects a duplicate.

Toggle Keys

Some keypresses toggle individual features on and off. Enabling the Toggle Keys function will have the system beep once when a toggle is turned on, and twice when it is turned off.

The mouse accessibility settings allow you to control the mouse pointer with the keyboard arrows instead of with the mouse itself. Click the Enable Mouse Keys checkbox to turn this feature on.

There are three settings for the Mouse Keys feature. You can set sliders for the maximum speed, the acceleration rate, and the delay between pressing the arrow key and the time that the mouse pointer actually begins to move.

17.4.1.2 Menus

The Menus button in the Control Center takes you to the special Nautilus view called Applications, which is a file display of your menu tree. There, you can edit the menus as though they were files. You can drag and drop items to move, add, or delete them, and change their names or descriptions by right-clicking on them and selecting Properties.

17.4.1.3 Password

Open this tool to change your password. You will be asked for your current password and your new password. You will have to type the new password twice to confirm it.

The tool may reject passwords if they are not long enough or are too easy to guess.

17.4.2 Look and Feel Settings

These sections provide settings for the overall look of your desktop by letting you choose the background, screensaver, theme, and keyboard shortcuts.

17.4.2.1 Background

Selects images, colors, and dispay effects for the part of the display that lies behind windows and menus. To use an image, select one from the list of default backgrounds, or add another by clicking the Add Picture button and selecting a file from your disk. Then choose how you want the image fitted to your screen. For very small images or tile patterns, choose Tiled; for larger images or those exactly the size of the screen, choose Centered. Images that are a different shape from the screen may be scaled to fit, or scaled symmetrically until the entire image fits on the screen. You can also choose No Image and just use a color. If the image doesn't exactly fit the screen, you'll see the background color behind it.

In the color section, select either a solid, single color, or a horizontal or vertical gradient of two colors. If you select a gradient, the color will fade from the first color to the second one, down or across the screen. Click the color box to select the colors.

17.4.2.2 Fonts

Here, choose the fonts you want GNOME to use in different situations, and how it should draw those fonts on your screen.

The top half of the font dialog displays the fonts your system uses; click on the current font to change it.

Application Font

The font used in dialog boxes, text areas, and menus.

Desktop Font

The font used to display desktop icon labels.

Window Title Font

The font used in window titles.

Terminal Font

The font used in the terminal emulator. This should be a monospaced font such as Courier.

The bottom half of the font dialog is taken up with font rendering options. Font rendering determines the method used to draw the actual fonts on your screen. You have four options:

Monochrome

Render the fonts only in black and white. This can lead to letters being somewhat jagged, but is faster.

Best Shapes

Also known as "antialiasing," this is considered the highest quality and is recommended for most standard monitors.

Best Contrast

Make sure that the letters are displayed in the sharpest possible contrast. Recommended for the visually impaired.

Subpixel Smoothing (LCDs)

This optimization method is best for flat-panel (LCD) monitors.

17.4.2.3 Screensaver

Contains settings for the screensaver. You can choose from a list of available screensavers (including a random setting). Input the number of minutes of inactivity before the screensaver starts and whether you will be required to give your password before going back to the desktop. Power management settings are available here if your system is configured for them.

17.4.2.4 Keyboard Shortcuts

The Keyboard Shortcuts tool lets you choose the key combinations that will execute a wide range of actions, from opening the Run Command dialog or taking a screenshot to moving windows between workspaces.

To choose a new keyboard shortcut, click the action you want to change and then type a new accelerator. Setting a shortcut that conflicts with an existing GNOME shortcut will disable the old shortcut. Setting a shortcut that conflicts with one for any other application will usually override the application's shortcut.

17.4.2.5 Theme Selector

Themes provide a consistent overall style to the many widgets and components used by GNOME. A number of basic themes are included with the gtk-engines package, and you can download and install additional themes from http://gtk.themes.org.

Any themes installed on your system are listed in the Theme Selector. You can select one, and the theme will be applied to the desktop immediately.

If you have downloaded a theme and wish to install it, click the Install New Theme button. Provide the name and location of the .tar.gz or .tgz file and click OK. The new theme will be installed in the /usr/share/themes directory and be available for you to use on your desktop.

17.4.3 Hardware Settings

In some systems this section is called Peripherals. It includes tools that allow you to control the way your system works with hardware and peripheral devices such as your mouse and keyboard. If you have installed PalmOS device software, you may also have Palm Pilot configuration tools. Some systems also include a printer configuration tool here.

17.4.3.1 Keyboard

Contains settings for keyboard autorepeat and sounds. You can set the repeat rate of a pressed key and the delay before it starts. You also can enable keyboard clicks and their volume. Settings can be previewed by typing in the Test Settings textbox.

Three sliders adjust the volume, pitch, and duration of the keyboard bell. Click the Test button to hear the bell's new settings.

17.4.3.2 Mouse

Lets you configure the mouse for either a right-handed user or a left-handed user. If you configure for a left-handed user, all documentation about the left button applies to the right button, and vice versa. You also can set the acceleration and threshold (sensitivity) of the mouse.

17.4.3.3 Sound

This tool sets up a sound scheme for various actions. You can enable or disable all system sounds by checking the box "Start the sound server when I log in." To add sounds to particular events, check the box "Play sounds for specific events."

The rest of the window contains a listing of events, sorted by application. Each event with an associated sound has the name of the file played when it occurs. Select an event from the listing and click Play to hear its assigned sound.

To change the sound for an event, click on the event and then enter the name of the file or click Browse to choose a file to play.

17.4.4 System Settings

The System Settings category contains settings that relate to the internal operation of your desktop and operating system, such as the time or the way that files are associated with applications.

17.4.4.1 Date and Time

You will need your system's root password to change the date and time, since time affects all users on the system. The appearance of the time tool itself may vary depending on the operating system you use, but it will present you with options for choosing the time, date, and time zone for your system.

In addition, most time and date tools allow you to set one or more network time servers with which to synchronize, so your clock will never be inaccurate.

17.4.4.2 File Associations (MIME Types)

This tool also varies between operating systems. On most it is called File Associations, but on some it is called MIME Types. It allows you to set the applications that open particular files or handle particular network protocols. There are a bewildering number of file types listed here, sorted by category. For example, HTML documents are in the World Wide Web section of the Documents category, and have filenames ending in .htm and .html.

To add a new type of document, click the Add button. A dialog will open asking for the category/type listing for the file type and the extensions to associate with it. Then, choose an application (if any) that handles that document. Optionally, you can supply up to two regular expressions to identify the type. For example, if you installed the RealPlayer music software and wanted to add RealAudio music files to your system, you would list the .ram, .rm, and .ra file extensions (but not .rpm, which is used for the RPM software package format), and place the MIME type in the Audio category. Then, you would enter the name of your RealAudio application.

To edit an existing file association, select its listing and click the Edit button. You will see a dialog box in which you can choose an icon to be used for the file type, add or remove file extensions, and supply commands that will open, view, and edit this type of file. To delete a type, select it from the list and click the Delete button.

You can also choose protocol handlers, the applications that work with various internet services. To change your web browser to Galeon, you would open the World Wide Web (http://) item in the Internet Services section and set it to run /usr/bin/galeon. Some distributions replicate this ability in a tool called URL Handlers, described next.

17.4.4.3 URL Handlers

Not all distributions have this tool, as it replicates some of the functionality from the File Associations tool. The URL Handlers tool allows you to adjust the settings for special URL launchers used by the GNOME help system. The defaults for protocols such as HTTP, FTP, and Mail are already set and likely handled by your default web browser (for example, Galeon). The special URLs are ghelp, info, and man (i.e., GNOME help files, command info files, and man files). The defaults use the help browser for these types of files.

17.4.4.4 Manage Software

Not all distributions have this tool, which opens the Ximian Red Carpet software management application. You can use Red Carpet to install, remove, or update the software on your computer. There isn't room to describe this tool completely, but you can find complete instructions in its help menu.

17.4.4.5 Network Proxies

A proxy is a system that stands between your computer and the Internet, handling all the connections for you. If your system uses a proxy, you can name it here to allow all GNOME applications to take advantage of it.

You may set a proxy for HTTP, Secure HTTP (HTTPS), FTP, and Socks transactions. To do so, click the "Manual proxy configuration" radio button and enter the name of the proxy and, if necessary, the port number. Leave an entry blank if you do not use a proxy for that protocol.

Some networks have automatic proxy configuration, which allows you to enter a single URL and let the computer set the proxy names and port numbers. If this is the case, click the "Automatic proxy configuration" radio button and enter the URL for your proxy configuration host.

17.4.4.6 Sessions

This tool controls session management—that is, what happens when you log in and log out. The options are divided into three categories: general session options, settings for the current session, and startup programs. If you create multiple session types, you can choose among them when you log in. Most distributions have at least a few different sessions created for you in advance; you can select among them at the login screen.

The Session Options tab contains:

Show splash screen on login

Normally, GNOME displays a "splash screen" image to show you what's going on as it starts up. If you prefer not to have this appear, uncheck this box.

Prompt on logout

Normally, when you select the Log Out item from your System menu or GNOME menu, you will be asked if you really want to log out, and whether you would like to shut down, restart, or just log out. If you want the system to log out without confirmation, uncheck this box.

Automatically save changes to session

When you log out and leave applications running, GNOME will normally remember that the application was running, and start that application again the next time you log in. If you prefer not to have that happen, uncheck this box.

Sessions:

You can create alternate sessions and select them from the GNOME login screen before you log in. You could, for example, create a "work" session that would start your calendar and spreadsheet as soon as you logged in, and turn down the volume on your speakers. Another session might turn the volume up and start your web browser and a game. To make changes to a session beyond renaming it, log into that session and change it there.

The Current Session tab shows the programs that are running right now. Each application is assigned a number to indicate the order in which it is started (lower numbers are first). You can also assign a style to each application, which determines how it starts, restarts, or quits.

Normal

The application starts automatically when you log in and runs until you quit.

Restart

The application starts when you log in, and restarts itself if you stop it or if it crashes. The Metacity window manager and the panel have this style because they need to be running at all times.

Trash

The application doesn't start when you log in.

Settings

The application starts before other applications and is used to store configuration settings. Very few applications get this style.

The Startup Programs tab allows you to start an application every time you log in, whether or not it's running when you log out. To add a program to your list of startup applications, click the Add button and enter its name or select it by clicking Browse and selecting it in the filesystem.

17.4.5 Advanced Settings Control with GConf

GConf is the name of the GNOME configuration database. It acts as a central repository for settings and other shared system data, much like the Registry in Microsoft Windows. It uses XML files stored in the ~/.gconf directory to associate keys and values that multiple applications can access. It's possible to change those values with a text editor, but the gconf-editor application provides a much easier way to adjust variables and settings. It displays keys and their values in a convenient heirarchical fashion, together with any explanation of the key and its available values.

The gconf-editor program is not generally supported and is not the recommended tool for general-purpose configuration. It does not have an Undo feature; if you break something and can't figure out how to fix it, you can revert to the system default GConf database. To do so, log out, log into a command-line or non-GNOME environment (Ctrl+Alt+F1 will get you a virtual console in most systems), and delete the .gconf directory in your home directory. The default settings for GNOME applications will be restored when you next start your applications. Do not delete your .gconf directory while running GNOME.

To begin working with GConf keys, run the "gconf-editor" command at the command line or in the "Run Program..." dialog. The editor has a filesystem tree on the left, and an area on the right that is used to display keys and values. There are five groups of keys at the top level, but only two are really relevant to most users: apps, where you'll set preferences for applications, and desktop, which stores most of the keys set by the GNOME Control Center. There are too many keys and values to list here, but the examples in the rest of the section should give you a feel for what you can do with them.

Note that most of these configuration variables are loaded only when a program starts, so changes will not take effect until you restart the relevant application.

17.4.5.1 Window managers and window behavior

The window manager is the individual piece of software that handles the particulars of placement, movement, and border style of the windows on your desktop. The default GNOME 2 window manager is called Metacity.

Except for themes, almost none of the Metacity options are settable in the standard GNOME Control Center. To set them, select "apps" and then "metacity" in the gconf-editor. Metacity has a "general" category, where most of the options are set, plus a number of key bindings for window and workspace control. The most commonly changed items are:

auto_raise

If the box is checked, windows that get mouse focus automatically come to the front of the screen. If you set the focus mode to sloppy and leave this box unchecked, you can type into windows that are in the background. In the default focus mode, this setting has no effect.

focus_mode

GNOME 1.2 and 1.4 users will remember this feature, which lets you choose how windows get the keyboard focus. The default behavior is click: you must click on a window to bring it into focus. Other possible values are enter-exit (window focus comes to a window when the mouse does, and leaves when the mouse does) and sloppy (window focus comes to a window when the mouse enters it, and stays until the mouse enters another window).

animation_style

Choose the style of animation for moving, resizing, and minimizing windows. Your options are wireframe, thin, opaque, and none.

wrap_style

This item is a good example of the sort of feature that has been removed, hidden, or abstracted away in GNOME 2. The settings chosen here determine what happens when you use the key combination (normally Ctrl-Alt-Arrow, and set in the global_keybindings section of the Metacity keys) to try to move beyond the defined borders of your virtual desktops. If the value is none, you will not move any further. If the value is classic, movement leads you to the next workspace in number: going right from the rightmost workspace in a row will take you to the first workspace in the next row, and moving down from the bottom workspace in a column will take you to the top workspace in the next column. If you select toroidal, the workspaces behave as though they were on a globe: moving from the end of one row will take you back to the beginning of the same row.

17.4.5.2 The panel

As mentioned earlier, many panel options have been left out of the Panel Preferences tool that you get when you right-click on the panel. Some of the items you can adjust with gconf-editor are:

panel_show_delay and panel_hide_delay

If you have a panel set to automatically hide itself when you leave it alone, these values are the time in milliseconds that you leave it alone before it hides itself, and the time it takes to appear when you move the mouse to its side of the screen.

tooltips-enabled

Some people don't like tooltips in their panels. Setting this key to false (unchecking the box) will turn them off.

enable-animations and panel_animation_speed

When you hide or show a panel, it slides on and off the screen smoothly. These values allow you to turn off animation entirely or have it move faster or slower.


17.5 History and Changes in GNOME 2

Most new software releases add features, and a major complaint among users is of steadily increasing complexity, or "feature creep." The GNOME 2 desktop is distinctive in that, while adding a few features, it has also removed some features.

Many configuration formats have changed between GNOME 1.4 and GNOME 2.0 as applications have moved to using the GConf system. You will need to reconfigure most, if not all, of your applications when you upgrade.

New features include:

  • Font smoothing (antialiased fonts).

  • Marked speed increases in the Nautilus file manager.

  • Tabbed browsing (press Ctrl-T to create a new tab) in both Galeon and Mozilla web browsers.

  • Internationalization support, including proper handling of right-to-left languages.

  • Accessibility tools for people with visual or mobility impairments.

  • Control Center more smoothly integrated with the rest of the system.

Removed features include:

  • Edge flipping (dragging items from one desktop to another) is no longer available; use keyboard shortcuts or the Workspace Switcher Applet instead.

  • Detachable menus have been disabled; you can turn them on with the gconf-editor tool.

  • It is no longer possible to choose window placement algorithms. Some versions of GNOME ship without window focus options and leave them only as gconf keys.

  • GNOME 1.x made a distinction between two types of virtual desktops. Workspaces assumed the creation of multiple distinct desktops, whereas viewports assumed that you were creating a single, large desktop and displaying only a portion of it. Few people ever fully understood the distinction, and it has been removed from Metacity and the Workspace Switcher. As a result, windows moved to the edge of the screen no longer appear in the next workspace over, and it is not possible to create a three-dimensional array of virtual desktop areas.

  • Application display fonts, themes for window borders and application buttons, and the virtual filesystem's HTTP proxy have been given simplified configuration tools that appear in only one place. Several other Control Center tools have been eliminated, and the term "capplet" has been removed from the GNOME vocabulary.

  • Both menu configuration tools (gmenu and the menu display options tool) have been replaced by the ability to edit menus in Nautilus (type the location "applications:///" into Nautilus).

  • Many of the less important panel options are available only in the gconf-editor, including panel movement speed, the delay before hiding the panel when using the automatic hiding option, menu caching, and the option to display an image on the left side of the GNOME and Programs menus.

  • There are far fewer panel applets. Notably, there is only one clock applet rather than five (nobody admits to thinking five clocks were ever necessary) and there are only two applets in the "Amusements" category: eyes that track the mouse, and the fish that tells your fortune.

  • The Nautilus file manager also has fewer options. Notably, speed has been improved to the point that the Performance Tradeoffs are no longer necessary, the User Levels feature has been removed, the theme, font, and HTTP proxy settings have been moved to the Control Center, and the Help display has been moved to a dedicated help browser called yelp.

Most of these feature removals stem from switching from Sawfish to the much simpler Metacity window manager. However, all of the features that ended up being removed had initially sprung from one of the major pitfalls of any software project, especially open projects where making an executive decision is harder. When developers disagree, it is often easier politically to create an option than to find an acceptable compromise or enforce a "correct" decision. However, each preference, option, and feature adds another layer of complexity, making the software harder to support, debug, and integrate with the rest of the desktop.

The clearest example in GNOME is window management software. The window manager is important and complex software: it controls window placement and ordering, controls event handling and focus, and so forth. Without a window manager, your desktop would not be functional as you know it. At the same time, window managers have to be completely unobtrusive, or they interfere with the use of applications. Most computer users do not know or care what window managers are, and have certainly never started a window manager by hand themselves.

When GNOME 1.0 was released, it allowed users to select among various window managers, including twm and icewm. The majority of users and distributions used a window manager called Enlightenment, which quickly grew from being a window manager to being a desktop environment in its own right. Running GNOME and Enlightenment at once became increasingly redundant, so for GNOME 1.2 and 1.4, users and distributors switched to Sawfish, which was small, fast, and highly configurable.

In fact, there were so many combinations of settings that it was hard to test, and it kept getting larger and more complex. By the time GNOME 2.0 was on the way, Sawfish was slow, large, and impossible to maintain. The Sawfish maintainer had abandoned it, and nobody was willing to continue the project.

The GNOME development team was determined not to repeat the process. Metacity, the GNOME 2 window manager, is small, fast, and simple. The GNOME Control Center is designed around the assumption that most users do not care to pick or know their window manager, and that developers do not care to bear the burden of code complexity caused by interacting with multiple window management systems. It's still possible to switch window managers, and those who wish to do so can do it by editing their ~/.gnome-session files.

The GNOME 2 series of releases (2.0 and 2.2 have been released as of this writing; 2.4 and 2.6 are planned) aims to choose good defaults rather than offer limitless options, and considers simplicity and usability to be as important as adding additional behavior. The desktop is kept as simple as possible so that it does not distract from the actual functionality of the applications that are based upon it and that are its real reason for existence. The applications themselves are not shying away from new features or new capabilities, but for the most part share the goals of simplicity and ease of use.


Chapter 18. KDE

The K Desktop Environment (KDE) is an open source software project that provides a consistent, user-friendly, contemporary desktop for Unix and Linux systems. KDE is not simply a window manager like fvwm, but a whole desktop environment including services to assist end users, application developers, and system administrators in standardizing the look and feel of their applications and configuring their systems. The KDE interface makes full use of drag-and-drop functionality so that, for instance, you can grab an icon for a text file in the file manager and drag it to a text editor window to open it. Full network integration of KDE applications allows you to transparently access files from other computers or FTP sites and manipulate them as if they were local.

KDE also implements a standard help system based on HTML. Applications that display a Help button offer a specific file of documentation for that application in the help viewer.

One goal of KDE is to provide the user with system information and configuration through easy-to-use graphical interfaces on the desktop. The KDE Control Center is a central utility for desktop and application configuration, as well as a source of information for important system components. The Information module of the Control Center can retrieve and display status information for your processor, memory, PCI bus, network devices, and many other hardware components on your system.

A wide variety of applications has been developed to take advantage of KDE's features and provide the user with a wealth of productive applications. The base package comes with programs such as a mail client, a calendar and organizer, a CD player, image viewers, chat programs, and more.

Most Linux distributions ship with KDE and allow you to set it up as the default session environment when you install the operating system. If you are installing KDE separately, download and install the KDE packages (you can find them at ftp://ftp.kde.org, among other places). You can also use this link if you want to upgrade your version of KDE with the current official version.

Red Hat 8.0 has introduced a new look and feel called Bluecurve. For the most part, the applications and services offered on the KDE desktop under Bluecurve are the same as those described here, but they may appear in different places or have different names and icons. For instance, the startup menu at the bottom left corner of the screen, which displays a large K in vanilla KDE, displays a red hat in Bluecurve.

To set KDE as your desktop environment, look for the X initialization files in your home directory. Depending on your distribution and how you log in, look for .xinitrc, .xsession, or .Xclients in your home directory. If none of these files exist, create a new .xinitrc file. Edit the file to remove any window manager references that may exist and add startkde on a line at the end of the file. If you are logging in through the KDE or GNOME display manager, there may be a Session tab or icon that allows you to select KDE as your desktop environment. In that case, you do not need to update or add an initialization file.


18.1 Desktop Overview

Figure 18-1 shows a typical KDE desktop. The bar across the bottom of the screen is the panel. It contains buttons for the main menu (often referred to as the K menu), the window list, the desktop pager, and the taskbar, as well as other buttons used to launch applications. The taskbar is used to keep track of application windows running on the desktop.

Figure 18-1. The KDE desktop

The desktop displays several open application windows and contains icons that can be used to launch applications with a single click. Several icons are placed on the desktop by default. The Trash icon is a link to a special desktop folder to which you can drag files that you want to delete. There are also icons that link to a mounted CD-ROM and an unmounted floppy drive.

18.1.1 Application Windows

Each KDE window has a titlebar with common buttons on the right for minimize, maximize, and close. On the left side of the titlebar, there is a small icon (or a dash if an icon isn't specified by the application) and a button that looks like a pushpin. The icon opens the window menu that contains a number of different functions you can apply to the window, such as sending it to another desktop. The pushpin button is used to stick or unstick the window to the screen. If you click on the pushpin, the window becomes sticky and appears on all of the virtual desktops. The button appears pushed in when a window is sticky. Click the button again to unstick a window.

The window menu contains standard window commands: Maximize, Iconify, Move, Resize, Sticky, Always on Top, and Close. There is also a command that lets you send the window to another virtual desktop.

Double-click on a window's titlebar to "shade" the window. Shading a window causes it to roll up and disappear into the titlebar, making space on the desktop.

18.1.2 The Konqueror File Manager and Web Browser

One of the most important KDE applications is Konqueror. Konqueror is both a graphical file manager and an Internet browser. Any time you click a folder icon, such as the Home folder button on the panel, a Konqueror window opens, displaying the contents of the directory. Konqueror also provides the underlying engine for the Help Center and the Control Center. Figure 18-2 shows a Konqueror file manager window displaying a home directory. Files and directories are shown as icons by default, but you can use the View menu to view contents with more detail.

Figure 18-2. The Konqueror file manager

Like other web browsers, Konqueror has a toolbar that contains back and forward buttons for stepping through your selection history, a home button, reload, and stop. The Location bar uses URL addressing for both network addresses and local filesystems. These features are therefore available to the file manager aspect of Konqueror as well as to the web browser aspect. Depending on the URL you enter, Konqueror opens either in browser or file manager mode. You can also split the screen into multiple windows and have, for example, one window open to your home directory and another window open to a web site. If you want, you can even open a terminal window from Konqueror, making it an almost complete working environment.

18.1.3 The Konsole Terminal Emulator

If you are used to working in a terminal window, you can still do that in KDE. Konsole, KDE's terminal emulation program, can be started from the K menu or from a button on the panel. Once a Konsole window is running, you can open new terminal sessions in a single Konsole window, saving space on your desktop. To start a new session, go to the Session menu and pick the session type you want to open, or select a session type by clicking the New button at the bottom of an open Konsole window. The choices are:

New Shell

Opens a new Konsole terminal shell.

New Linux Console

Opens a session that emulates a text-only Linux terminal.

New Midnight Commander

Opens a session with the Midnight Commander file manager.

New Root Console

Opens a root console session.

New Root Midnight Commander

Opens a root Midnight Commander session.

New Screen Session

Opens a session that uses the screen screen manager, which permits multiple virtual terminals to share a single physical terminal.

If you pick an option that opens a root session, Konsole prompts for the root password before starting the session. Each session adds a button at the bottom of the Konsole window; use the buttons to switch between sessions.

18.1.4 Adding a Link to the Desktop

There are a couple of ways to add a desktop link. The simplest way is to right-click on the background and select New from the Desktop menu that appears. The New menu offers a number of choices for the type of link to create: Directory, Link to Application, Link to Location (URL), Floppy Device, Hard Disc, CD/DVD-ROM Device, Text File, or HTML File. If you have KOffice installed, you'll also see options to add Office documents. When you make a selection, the properties window for that link type appears.

The properties window varies slightly depending on the type of link, but for most links you need to specify a name for the link file, the label for the icon, and the executable command or file location. You can also set the permissions for the link file and select a new icon.

The following example shows how to create an application desktop link that opens the Kate text editor. First, right-click on the desktop and select New [image] Application. The properties window opens, showing four tabs: General, Permissions, Execute, and Application.

The General tab shows "Link to Application" in the text box. That text represents both the name of the link file being created and the text that appears under the icon on the desktop. Enter a filename that reflects the purpose of the link; in Figure 18-3, it is Kate.

The tab also displays an image of the icon that will appear on the desktop and additional information about the file. The default icon for an application is a picture of a gear. You can change the icon by clicking the button showing the current icon. This opens a window that displays a set of default KDE icons found on your system. Pick the one you like and click OK.

Figure 18-3. General tab of desktop link properties

Because you created the link file, the permissions allow you to use it. If you want to adjust the permissions, go to the Permissions tab. The next step is to supply the command used to open the application. On the Execute tab, type in the command, or click the Browse button to locate the file (Figure 18-4).

Figure 18-4. Execute tab of desktop link properties

The final step is to supply a tooltip comment. Fill in the Comment box on the Application tab with a description of the application (Figure 18-5). Click the OK button to finish the configuration. If you want to change a property of your link later, right-click on the icon and choose Properties.

Figure 18-5. Application tab of desktop link properties

When you create a link to a URL, a window appears with the text "New Link To Location (URL)" and an empty text box (Figure 18-6). Enter the URL in the text box and click the OK button.

Figure 18-6. Desktop window for URL link

Entering a new directory link is similar to entering a URL link, except the prompt above the text box reads "New Directory." Enter the path to the directory, and click the OK button.

For a new device link, select the appropriate device and set the link name and permissions if needed. On the Device tab, select the device from the drop-down list. That sets the device location, such as /dev/fd3, and displays the mount point as well.

You can also add a link to the desktop by dragging an item from a file manager window. You can do this with any file or directory. After you drag the item to the desktop, a small pop-up window asks whether you want to copy, move, or link the item. Copy simply makes a copy of the item in the Desktop directory; move removes the item from its original location and places it in the Desktop directory. If you choose link, the desktop icon contains a symbolic link that points to the item's current location.

18.1.5 The Desktop Folder

Everything that appears on the desktop exists in the ~/Desktop folder. If you open this folder in the file manager, you may see directories for Templates and Autostart, as well as files for the CD-ROM and floppy drive and any other links you have set. When KDE starts, it scans the contents of the Desktop directory and creates icons for each item.

Desktop links that launch applications, URLs, or files are configured in the background by .desktop files. These are simple text files that contain all the information that you set for a link in the link properties dialog boxes. Although all configuration of desktop links is handled thoroughly by the configuration pop-up windows, the contents of .desktop files may be of interest. The following example shows the .desktop file for a link to the Kate text editor:

    # KDE Config File

    [Desktop Entry]

    Comment[en-US]=The Kate text editor

    Encoding=UTF-8

    Exec=kate

    Icon=

    MimeType=

    Name[en-US]=Kate

    Path=

    ServiceTypes=

    SwallowExec=

    SwallowTitle=

    Terminal=false

    TerminalOptions=

    Type=Application

    X-KDE-SubstituteUID=false

    X-KDE-Username=

    ...

As you can see, the syntax is simple and straightforward. The items filled in on the properties windows are listed on each line of the file. The Type line identifies the kind of link file. In this example, Kate is an application; Type=URL would indicate an Internet address link file. The Name line lists the name of the application, Comment lists the comment you added to describe the application, Exec lists the command, Icon identifies the icon image file for an icon other than the default, and so on. Unspecified options have empty values. The Name and Comment lines include the language in square brackets.


18.2 The Panel

The panel is the control bar across the bottom of the screen, used to find and launch applications and navigate among windows and desktops. It contains the K menu (identified by the KDE K logo), which organizes the installed KDE applications into submenus; the Desktop Access button, which minimizes all open windows to display a clean desktop; and the desktop pager and the taskbar. Additional buttons that open applications, directories, and URLs can be added to the panel.

18.2.1 The Desktop Pager

Like most window managers, kwin (KDE's window manager) can divide your workspace into multiple desktops. Different application windows can be open on each desktop, reducing the amount of clutter on your screen. You can switch among desktops by using the desktop buttons on the panel. The panel displays a grid of buttons called the pager. The pager has one button for each virtual desktop, and shows images of the open windows or their names (1, 2, 3, etc., by default). Clicking on a button switches your screen to the corresponding desktop.

Clicking the wider vertical bar to the left of the pager opens a Desktop Pager window. If your version of KDE does not have that bar, right-click on the pager itself and select Launch Pager. The Desktop Pager has larger buttons for each desktop and an actual icon for each application running on that desktop, making it easier to tell what applications are running.

You can configure the number of virtual desktops and their names in the Control Center by selecting Look & Feel [image] Desktop and clicking the Number of Desktops tab.

18.2.2 The Taskbar

The taskbar runs in the panel and helps you keep track of running applications. It contains buttons to identify each open application window. If the button for an application is clicked, that becomes the current active window. When you iconify a window, you can raise it again by clicking its button on the taskbar. If a window has been iconified, its taskbar button contains a parenthesized text label. If multiple instances of one type of window are running, they are represented by a single button in the taskbar, with a small up-arrow on the right. Click the button to display a list of the instances and select the one you want.

Clicking the wider vertical bar to the left of the taskbar displays a menu divided into sections for each desktop and items for each window they contain. (This window list is also accessible by middle-clicking on the desktop background.) For example, if desktop 2 contains an open Konqueror window, you can click on its entry in the window list, and the window manager switches you to desktop 2 and activates the Konqueror window.

You can add an external taskbar to the desktop, either in place of or in addition to the one running in the panel. The external taskbar runs along one edge of the desktop, usually the top or bottom. You can configure the location and other settings of the external taskbar in the Control Center by selecting Panel [image] Extensions.

18.2.3 Adding an Application Link to the Panel

The simplest way to add an application button to the panel is by dragging an icon from the desktop to the panel. This copies the link from the desktop. Any application listed in the K menu can be easily added to the panel. From the K menu, choose Panel [image] Add Application, then select from the submenus or items that are listed. The choices you have are the same items that appear on the K menu.

To remove a button from the panel, right-click on an empty place on the panel to bring up the panel menu, and select Remove. That displays another menu that lets you remove applets such as the pager or taskbar, buttons that start applications, or special buttons such as the K menu or the Desktop Access button. You can also right-click on an icon and select Remove.

18.2.4 Running an Application on the Panel

A swallowed application, or applet, is a program that runs on the panel instead of in a desktop window. A swallowed application can be a small utility that monitors network activity or provides mail notification, for example. The lock/login applet, the klipper clipboard applet, and the clock are examples of swallowed applications, as are the pager and the taskbar when they're running in the panel. Add other applets by selecting Add [image] Applet from the panel menu and selecting the applet you want.


18.3 The KDE Control Center

The KDE Control Center contains a number of configuration tools, called modules, that allow you to configure and view information about your system. You can configure the desktop, window behavior and decoration, input devices, and any other important part of your system here.

The Control Center is split into two windows: the left window shows a hierarchical list of installed modules, and the right window displays the modules when they are selected. (You can also run individual Control Center modules by selecting the one you want from the Preferences option on the K menu.) Start the Control Center from the panel button with an icon of a circuit board in front of a terminal, or from the K menu. Many of the modules can also be accessed directly from their applications, by right-clicking on the application icon and selecting Preferences, or by right-clicking on the titlebar of the running application window and selecting Configure.

Context-sensitive help is available for Control Center modules by clicking on the question mark on the titlebar and then on the setting for which you want help. You can get a brief general help message for the currently open module by clicking the Help tab in the left window; each help message also contains a link to the module's manual. Or you can get help by opening the Help Center, selecting Applications [image] Preferences, and then choosing a module.

The middle tab in the left Control Center window lets you search. You can enter a term in the text box at the top to narrow the list of keywords, or scroll through the keywords. When you find the one you want, click on it to highlight it. The Results box at the bottom will display a list of modules for which the term applies; select a module from the list and that module will appear in the right-hand window. For example, selecting the keyword audio displays the results Sound, Sound Server, System Bell, and System Notifications. If you select Sound Server from that list, you can view or change the Sound Server settings.

The following sections describe the modules. The number and type of available Control Center modules vary depending on your Linux distribution and which version of KDE you are running. You may find that some of the modules described here are not on your system, that you have others that we don't describe, or that some of the specifics are different. In general, however, these descriptions should give you a good idea of how to go about configuring your KDE desktop.

18.3.1 File Browsing

The File Browsing modules are used to set file associations and to configure Konqueror's file management features.

18.3.1.1 File Associations

This module associates a filename extension with an application so that clicking on a file with that extension automatically opens the application with the file loaded. The utility divides files into various types based on the MIME standard used for email and the Web. Thus, under the text types you can find the html type. The file extensions .htm, .HTM, .html, and .HTML are associated with the html file type.

The window initially has only a text box where you can enter a filename pattern to search for the matching application and a list of known applications. You can also add and remove types from the list.

When you select an application from the Known Types list, the right side of the window displays options for that file type. The General tab shows the patterns associated with the application; you can add others or select one of the patterns to remove it from the list. Clicking on the icon image opens the Select Icon window for choosing a different icon to use with that file type. Application Preference Order lists the applications associated with that type. You can add applications to the list with the Add button; select an entry to activate the other buttons. You can then move the entry up or down on the list, edit it, or remove it from the list.

On the Embedding tab, the set of radio buttons determines whether a file is viewed in Konqueror or in an application window.

18.3.1.2 File Manager

This module contains configuration settings for the Konqueror file manager. The Behavior tab sets some global options, such as whether opening a directory also opens a new Konqueror window or if you want a dialog box to show the progress of a network file download. On the Appearance tab, you can set your choice of font, font size, and text color. Other options on this tab include whether to wrap or truncate icon text, underline filenames on the desktop, or display the file size in bytes (otherwise kilobytes or megabytes are shown for large files) in tree, detailed list, and text view modes. The Trash tab determines whether you'll be asked for confirmation when moving a file to the trash, deleting it, or shredding it. For every file type checked on the Previews tab, the Konqueror file manager displays a mini-preview of the file contents instead of an icon.

18.3.2 Information

The Information modules allow you to view status information about various system components. There are no configuration settings here, but if you need to see information about your processor or what PCI devices you have installed, use these modules. Information is provided for the following system components:

  • Block devices

  • Devices

  • DMA-Channels

  • Interrupts

  • IO-Ports

  • Memory

  • Network interfaces

  • Partitions

  • PCI

  • PCMCIA

  • Processor

  • Protocols

  • Samba status

  • SCSI

  • Sound

  • USB devices

  • X-Server

18.3.3 Look & Feel

The Look & Feel modules determine the appearance of the KDE desktop and configure it to work in a way that is comfortable for you.

18.3.3.1 Background

This module sets the desktop background. It allows you to specify a background for each virtual desktop or just one background for all of them. Select the desktop you want to configure from the list, or check the Common Background box.

On the Background tab at the bottom of the window, select whether you want a flat (Solid color) background, a pattern, or one of several gradients from the Mode drop-down box. If you select a pattern, click the Setup box, and the Select Background Pattern window will open. Select a pattern from the choices or add your own, and click OK. For a pattern or gradient, choose colors for Color 1 and Color 2 by clicking on the color bars. For a flat background, choose a color from the Color 1 color bar.

On the Wallpaper tab, you can choose No Wallpaper, Single Wallpaper, or Multiple Wallpaper. If you are using wallpaper, the Mode setting determines how the image file is laid out. You can choose a tiled layout, or various centered or scaled options. If you want to use an image file as wallpaper on the background, select it from the drop-down list, or click the Browse button to look for the image on the filesystem. To use multiple wallpapers, click the Setup Multiple button. Set the time interval that each wallpaper remains on the screen. The Mode button lets you cycle through wallpaper patterns in order or randomly. Choose the wallpapers to use from the list, or click the Add or Remove button to add or remove files from the list. When viewing available wallpapers, right-click the display and choose Thumbnail Previews to see what they'll look like.

The Advanced tab sets a blending pattern for a multicolored background. The choices range from no blending to horizontal or vertical blending to various patterns and intensities.

18.3.3.2 Colors

The Colors module allows you to select the colors for the various window widgets, the components used to build windows. You can select the colors based on a scheme installed on your system. Select one of the available schemes from the list, and click Apply to change the color scheme. You can also set colors for individual components. The top portion of the tab shows sample window components. Click on the component you want to configure, such as the active titlebar or window background, to select it, or select a component from the widget color list. Click the color bar under the list to open the color selector dialog box and choose your color. Other choices are to set the contrast of the component with the Contrast slider and to apply the colors to non-KDE applications.

18.3.3.3 Desktop

The Desktop module sets preferences for the visual display of your environment. You can determine the appearance of your desktop and the number of virtual desktops, the actions taken by mouse buttons, and other options.

On the Desktop tab, select the options you want. Enable Desktop Menu places a copy of the desktop menu as a menubar at the top of the screen. Enable Icons on Desktop lets you place icons on the desktop for easy access. If you also set Show Hidden Files on Desktop, all files in the Desktop directory are displayed, including hidden files. Programs in Desktop Window lets you set a running application such as xearth as your desktop background. From the list of file types under "Show Previews for," select any for which you want a preview displayed on the desktop instead of an icon. Under "Clicks on the desktop," select the action to be taken on a left, right, or middle mouse-button click.

From the Appearance tab, select your preferred font, font size, and text color. You can also select a background color if you want to view the background box of the label. By default, the background is transparent, allowing the desktop background to be visible. Finally, you can choose to have filenames underlined.

The Number of Desktops tab sets the number of virtual desktops you can divide your workspace into. The default is 4, and you can use up to 16. The slider selects the number of desktops. The desktops are listed, numbered 1 through 16. For each enabled desktop, the listing has a usable text box next to it. You can type in a label for each desktop that will be shown in the pager display on the panel. The default labels are Desktop 1 through Desktop 16.

The Paths tab lets you set the path to the desktop, trash, and Autostart directories and to the default path for documents. In most cases, you won't need to change the defaults.

18.3.3.4 Fonts

The Fonts module sets the default fonts used on your display. You can set the font for the following listed selections: General, Fixed Width, Toolbar, Window Title, and Taskbar. Click the Choose button for the font you want to change, and the Select Font window appears. From this, you can select the font you want, choose if you want it to be bold or italic, and select the point size. A sample of the selected font is displayed at the bottom of the window. You can also check the box labeled "Use Anti-Aliasing for fonts" to make the fonts appear smoother on the screen.

18.3.3.5 Icons

This module controls the display and behavior of icons on the desktop. The module has two tabs, Theme and Advanced.

On the Theme tab, select an icon theme. The sample icons at the top are displayed in the current theme. After selecting a theme, select Install New Theme to install it. At the bottom of the window, you can add a new theme to the list by entering the path in the text box or clicking the button at the right to open a File dialog window. You can also remove any theme except the default.

Icons are used for many purposes: in the file manager, on the panel, and so on. The Advanced tab configures icons individually for different uses. First, select the use that you want to configure from the list. For that use, select a size from the Size list, or "Double-sized pixels" to get very large, but somewhat blurry, icons. You can also choose to have the icons animated. The icon images at the bottom show how the icon will appear normally (default), when it is active (i.e., when the cursor is over it), and when it is disabled.

For each use, you can set special effects. Clicking the Set Effect button displays the Set Default Icon Effect window. From that window, select an effect and move the slider to determine the amount of that effect. For instance, choosing the To Gray effect for Active causes an icon to turn gray when you put the cursor on it. (To Gray is probably more appropriate for Disabled.) If you choose Colorize, the Color option becomes active so you can pick a color.

18.3.3.6 Launch Feedback

The Launch Feedback module has two options to provide visual feedback while an application is starting, so you know something is happening. If you check the box Enable Busy Cursor, a mini-icon appears and tracks the cursor. Under the Enable Busy Cursor option, checking Enable Blinking causes the icon to blink. Enable Taskbar Notification causes the taskbar entry to show a revolving timer while the application starts. Both options let you set a timeout, which has a maximum of 99 seconds. When the timeout period is over, the visual feedback stops, even if the application is not yet fully started.

18.3.3.7 Panel

The panel configuration module controls the panel's appearance, the panel's behavior, and the K menu layout, and it configures any extensions that are enabled.

On the Position tab, you can choose to place the panel at the top, bottom, left side, or right side of the screen by clicking the appropriate radio button. You can set the panel alignment to Left, Center, or Right. Five settings are available to set the size of the panel to either Tiny, Small, Medium, Large, or Custom. In the Length section, you can move the slider to set the amount of the width or height of the desktop that the panel occupies. If you set it to less than 100% and click the "Expand to fit required size" button, the panel will expand to take up as much room as it needs to fit all the icons.

The Hiding tab, shown in Figure 18-7, is divided into sections that provide options for hiding the panel when you want more visible desktop space to use as a work area. The Hide Buttons section contains checkboxes that enable the display of a hide button at one or both sides of the panel. Clicking on a hide button causes the panel to roll up into that side and disappear, leaving only a button you can click to have the panel reappear. Move the slider in the Hide Button Size section to set the size of the hide button. Checking the box in the Manual Hide Animation section enables the panel to use a sliding visual effect when you show or hide it with its side arrow buttons. The slider sets the speed of this animation. You can have the panel autohide (i.e., disappear when not being used) by checking the "Enable automatic hide" button and moving the slider to set the amount of time after the pointer has left the panel that the panel will hide. The panel reappears when you move the mouse over it. Checking the "Show panel when switching desktop" box causes the panel to reappear when you move to a different desktop. It appears on the new desktop and then hides again. You can set "Enable automatic hide animation" and move the slider to set the animation speed.

Figure 18-7. Panel hiding configuration

The Look & Feel tab contains settings for the appearance of the panel and its icons. Each icon is on a tile that by default is transparent, so all you see is the icon. If you set "Enable background tiles," the tiles are shown, and the settings in the middle of the window are enabled so you can enable or disable different tile types and set the background colors individually. The tile types are K-Menu, Quickbrowser, Application Launcher, Legacy Application Launcher, Window List, and Desktop Access.

Also on the Look & Feel tab, the "Enable icon zooming" setting causes icons to zoom large when you pass the mouse over them, so they appear to pop out at you. The "Show tooltips" option displays tooltips when you move the mouse over icons on the panel. To see an image on the panel background, set "Enable background image" and either enter the path to the image or browse to find one.

The Menus tab contains settings for the K menu and other menu layouts. Settings for the K menu include:

Show side image

Show a small image next to each menu entry.

Show "Bookmarks" submenu

Include a Bookmarks menu that shows your Konqueror bookmarks and lets you edit them.

Show "Recent Documents" submenu

Display a list of recently used files. Click the Clear History box to empty the list.

Show "Quick Browser" submenu

Add a browser menu for easy access to files without running the file manager. The top-level entries are Home Directory, Root Directory, and System Configuration to start from the user's home directory, the root directory, and /etc, respectively.

Detailed menu entries

Include a brief description of each menu item. If the box is not checked, only the application name is shown.

Below these settings are two columns, Available Menus and Selected Menus. The first column contains menus that are not in the K menu but can be added. The second column contains those you have selected to add. Highlight an entry in the Available Menus column and click the right-pointing arrow to move it to the Selected Menus column; do the reverse to unselect an entry. Click the Apply button to add the selected menus to the K menu. Once added, they stay in the Selected list.

To have browser menus show hidden files (i.e., dot files), select "Show hidden files in browser menus." Move the slider "Maximum browser menu entries" to change the number of entries a browser menu will display.

The Quick Start section is at the top of the K menu. Its entries consist of either the most recently used or the most frequently used applications, depending on which radio button is selected. Set the maximum number of entries shown in the Quick Start section if you want to change the default, which is 5.

The Extensions tab is active if you have added any extensions, such as a child panel or an external taskbar (by right-clicking on the panel and selecting Add [image] Extension). For each extension, you can locate it to the left, right, top, or bottom of the desktop, set automatic hide options, enable hide buttons, and specify the hide button size.

18.3.3.8 Screensaver

This module sets up your screensaver. A list of available screensavers is shown with a preview window. If you want to use a screensaver, check the Enable Screensaver box and select the screensaver you want to use. The Setup button opens a dialog box that contains specific configuration settings for each screensaver. For a full-screen test of the screensaver, click the Test button.

The Settings section allows you to set the amount of time the system is inactive before the screensaver starts. Type in the number of minutes in the Wait For box to set this time. If you check the Require Password box, the user must supply a password before returning to the desktop. You can also check the box "Show Password as Stars" to display the password text as asterisks instead of leaving the field blank. The Priority control lets you adjust the priority that the screensaver process has when it is run. If you have lots of important server activity, for example, set the priority to low so the performance of other programs does not suffer.

18.3.3.9 Shortcuts

Shortcuts are key combinations that do something to your desktop or application. By default, for example, Alt-F4 closes the current window. That's a global shortcut; there are also shortcuts used in specific applications.

You can choose the scheme used for shortcuts by selecting the KDE defaults or the current scheme if you have customized the shortcuts. The bottom section of the tab allows you to edit the selected keyboard shortcut. You can choose no key for the action, the default key, or a custom key. If you select custom, the Define Shortcut dialog appears. Here you can set or modify the primary or alternate shortcut. Click the X in the box pointing to the current shortcut, then click Multi-Key if you want to use any modifiers (Shift, Ctrl, or Alt). Finally, press the key or key combination on the keyboard that you want to use. Click Apply to save the change to the current scheme, or click New Scheme and then Save to save them as a new scheme.

The Modifier Keys tab shows the modifier keys for the current keyboard. It is not used for configuration, but is there simply to provide information.

18.3.3.10 Style

The Style module contains settings for the display of windows and icons. Choose a style from the Widget Style list on the Style tab. The bottom half of the window previews the selected style. If you check Enable GUI Effects on the Effects tab, you can set effects such as fade or animation for ComboBox, ToolTip, and Menu effects. You can also make menus translucent and specify the type and degree of translucency or opacity. (Note that translucency uses more system resources, so you might not want to use these effects on a slower system.) The Miscellaneous tab offers several toolbar and visual appearance options.

18.3.3.11 Taskbar

The Taskbar module configures the taskbar, both in the panel and on the desktop. It is not used to set where on the desktop the taskbar appears (do that from Panel [image] Extensions). To add or remove the taskbar from the panel, right-click on the panel and select Add or Remove and then Taskbar. To place the taskbar directly on the desktop or to remove it from the desktop, use the Extensions tab in the Panel module.

The Taskbar module settings include the following:

Show windows from all desktops

The taskbar shows all windows, regardless of which desktop they are on. You can then select a task and move directly to that desktop with that window active.

Show window list button

Add a menu button at the left edge of the taskbar that displays, when clicked, a list of all desktops and their windows. This is particularly useful if "Show windows from all desktops" is unchecked, since it lets you select a window on another desktop.

Group similar tasks

Combine multiple instances of any application into a single taskbar entry. The entry shows a small up-arrow. When you click on the arrow, a list of the instances appears and you can select the one you want.

Sort tasks by virtual desktop

Order the taskbar by desktop.

Show application icons

Show the application's icon along with the text on each taskbar entry.

The Actions section sets an action for each of the left, middle, and right mouse buttons. The possible actions for each are Show Task List, Show Operations Menu, Cycle Through Windows, Activate Task, Raise Task, Lower Task, and Minimize Task.

18.3.3.12 Theme Manager

Themes provide an overall visual style to your desktop, so you get an integrated look instead of having to configure items individually. A theme can determine the color scheme of windows, the font styles, icons, background, and even sound events for your desktop. Several themes are installed by default with KDE, and many more are available at http://kde.themes.org for download.

The Installer tab, shown in Figure 18-8, lists the themes you have installed on your system. These include global themes, which are stored in $KDEDIR/share/apps/kthememgr/Themes, and local themes, which you have installed or customized and stored in ~/.kde/share/apps/kthememgr/Themes. You can edit and save local themes. Global themes cannot be altered by individual users.

Figure 18-8. Theme Manager Installer tab

If you select a theme from the list, a sample desktop image using the theme is displayed on the tab with a short text description. To apply a new theme, select from the list and click the Apply button. The selected theme is copied to your theme manager work directory (~/.kde/share/apps/kthememgr/Work).

You can also manage installed themes on the Installer tab. To install a new theme that you have downloaded, click the Add button. Specify the filename and location of the theme's .tgz file in the pop-up dialog box and click OK. The Save As button saves the currently configured theme as a separate local package without altering the original theme. The Create button works similarly, allowing you to copy your current working theme as a new local theme package. The Remove button deletes a local theme or inactivates a global theme.

The Contents tab shows the components that are configured by a theme. A theme may not have settings available for all the listed components. If a theme configures a specific component, it is listed as available. Otherwise, the component is listed as empty. Use the checkboxes to select which theme components you want to use. If you choose not to activate a specific component, information on that component from a previous theme will be used if its information is still in the theme manager work directory. If you don't want this to happen, activate the component even if it is listed as empty, and default settings will be used.

18.3.3.13 Window Behavior

The modules in the Window Behavior module allow you to set the look and functionality of window titlebars, mouse button actions, and focus and placement policy.

On the Focus tab, the Focus Policy section sets the policy for giving a window keyboard focus and an active titlebar. The drop-down list contains four focus styles:

Click to Focus

This default focus policy requires a mouse click in a window to give it focus and raise it (bring it to the foreground).

Focus Follows Mouse

This setting causes a window to receive focus when the mouse pointer enters it. It does not come to the foreground unless the Auto Raise button is checked. The window maintains focus until the pointer enters another window.

Focus Under Mouse

This setting is similar to the Focus Follows Mouse setting, except that the window loses focus when the mouse pointer moves out of it. If the pointer is not in a window, no window has focus.

Focus Strictly Under Mouse

This setting is similar to Focus Under Mouse, but is stricter in interpreting when the mouse leaves the window.

For all the focus policies except Click to Focus, the Auto Raise and Click Raise boxes are available. One of these must be checked to be able to raise windows to the foreground. Auto Raise raises a window after a short delay, which you can set with the Delay slider.

The Keyboard section determines behavior when you use the keyboard to switch windows or desktops. In KDE mode, a box appears showing the window you are about to switch to. In CDE mode, no box appears. Check "Traverse windows on all desktops" if you want to move through all windows on all desktops. (CDE is an older desktop distributed with some commercial Unix systems.)

The Actions tab (Figure 18-9) configures the actions of mouse buttons on the various window components. Drop-down lists contain several options, such as raise or lower, for the left, middle, and right buttons. For each of the components, you can choose what happens when a mouse button is clicked. For instance, by default, right-clicking in a titlebar brings up an Operations menu.

Figure 18-9. Windows Behavior Actions tab

The Moving tab sets window and snap zone options. The Windows section of the tab has the following settings:

Display Content in Moving Windows

Enable the display of window contents when the window is moved.

Display Content in Resizing Window

Enable the display of window contents when the window is resized.

Animate Minimize and Restore

Enable animation and activate the slider, which controls the animation speed.

Allow Moving and Resizing of Maximized Windows

Allow the use of the border on a maximized window to move or resize the window.

Placement

Choose Smart, Cascade, or Random window placement from the drop-down list to determine the initial placement of new windows on the desktop. Smart placement attempts to keep windows as uncluttered as possible. Cascade attempts to place windows in a cascaded pattern, so at least an edge of each window is visible. Random placement puts each new window randomly on the desktop.

The Snap Zones section sets the width of the zone within which a window will snap to the desktop border at the edge of the screen ("Border snap zone") or to another window ("Window snap zone"). Both zones are set with sliders and default to 10 pixels.

The Advanced tab sets options for configuring window shading, the use of Xinerama, and active desktop borders. In the Shading section, check Animate to animate window shading and unshading, and check Enable Hover to cause a shaded window to unshade if the mouse pointer remains over the titlebar for the number of milliseconds determined by moving the Delay slider.

Xinerama is a feature of XFree86 that allows multiple monitors to be treated as one big monitor. KDE supports Xinerama; the Xinerama section is available only if Xinerama support was compiled into KDE.[1] The following checkboxes configure the use of Xinerama:

[1] The screens also need to be configured in /etc/X11/XF86Config.

Enable Xinerama Support

Enable the use of Xinerama with KDE.

Enable Window Resistance Support

Provide some resistance when a window moves to the edge of one monitor screen so that it doesn't accidentally move onto the next.

Enable Window Placement Support

Provide support for positioning windows on any portion of the logical desktop, regardless of which monitor it falls on. If window placement support is enabled, a new window appears on the screen where the mouse pointer is.

Enable Window Maximize Support

Permit windows to be maximized across multiple monitors.

Active desktop borders enable you to switch between desktops by moving the mouse pointer to an adjacent screen edge. In the Active Desktop Borders section, the choices are:

Disabled

Turn off active desktop borders.

Only When Moving Windows

Enable active borders only when moving windows across the edge, not when moving the mouse across.

Always Enabled

Active borders are enabled both for moving windows and for moving the mouse across the edge to another desktop.

The Desktop switch-delay slider sets a delay time for the switch to the adjacent desktop. Set this time to a comfortable setting that doesn't cause an unwanted desktop switch every time you move the pointer to the screen edge. The slider is active unless active borders have been disabled.

18.3.3.14 Window Decoration

The Window Decoration module sets preferences for the appearance of KDE windows. There are three tabs: General, Buttons, and Configure.

The Buttons tab configures the layout of buttons that appear on the titlebars of windows. It is available only if you check "Use custom titlebar button positions" on the General tab. There are five buttons: minimize (dot), maximize (square), sticky (pushpin), close (X), and menu (dash or application-specified icon). Each button has three placement options, specified by radio buttons: left, right, or off. You can place no more than three buttons on one side of the titlebar.

The options available on the Configure tab vary according to the window decoration style selected on the General tab. Depending on the style, they affect the appearance of the titlebar and buttons, and the width of the window frame. The tab itself shows the name of the current style. For some styles, no configuration options are available.

18.3.4 Network

The Network modules configure a number of networking features on your system. These modules don't configure the network itself, but set your personal preferences and configuration options. The primary networking modules in the Control Center include Email, Preferences, SOCKS, and Window Shares. These modules are described here. Depending on your Linux distribution and what applications you have installed, you may also see modules such as Kisdndock, which configures ISDN docking options; LAN Browsing to configure LISa, the LAN Information Server, which provides a TCP/IP-based "network neighborhood" for your network; and News Ticker, which is a news ticker applet that runs on the panel and provides running access to current news from sites you specify.

18.3.4.1 Email

The Email module provides a place for you to specify some basic pieces of information that KDE may use for email-related purposes. In the User Information section, you can specify your Full Name, Organization, Email Address, and Reply-To Address. In the Preferred Email Client section, enter the name of the email client you want KDE to use on your behalf. The default client is KDE's KMail, but you can enter another client or click the Browse button to find available clients. Check the Run in Terminal box if you use a text-based email client such as Pine.

18.3.4.2 Preferences

The Preferences module sets timeout values for "Socket read," "Proxy connect," "Server connect," and "Server response." If your connection is slow and you find that you are getting frequent timeouts, you might want to increase the values. This module also has an FTP Options section where you can check "Enable passive mode (PASV)" if you want to permit passive FTP transfers because you are behind a firewall, and you can check "Mark partially uploaded files" so that they appear in a directory listing with a .part extension until the transfer is complete.

18.3.4.3 SOCKS

The SOCKS module enables SOCKS support in KDE applications. SOCKS is a protocol that executes proxy requests on behalf of a client. If you have SOCKS installed and working, you can check the box "Enable SOCKS support." At that point, additional options become available. Click "Auto detect" to have KDE try to determine which SOCKS implementation you are using, or click NEC SOCKS or Dante if you are using one of those. Finally, if KDE can't detect your SOCKS implementation, you can enter one or more paths in the "Additional library search paths" section for KDE to search. Click the Test button to test your SOCKS support.

18.3.4.4 Windows Shares

The Windows Shares module configures your Samba client if you are running Samba on your network to communicate with Windows systems. This module configures the client, not the Samba server, so that Konqueror can access shared Windows filesystems from other computers.

Enter your default username, default password, and workgroup in the three text boxes at the top of the window. Check the box "Show hidden shares" if you want to see shares whose names end with a dollar sign ($).

Note that entering your password and having KDE store it on the system is a security risk. If you don't enter your name or password and they are required to access the shared Windows system, you will be prompted for them. That's less convenient, but safer.

18.3.5 Password

The Password module is available in some distributions, including Red Hat 8 with Bluecurve, allowing you to change your login password. This module prompts you for your current password and new password, and then asks you to re-enter the new password.

18.3.6 Peripherals

The modules here control the configuration of the keyboard and mouse. These settings affect only your use of KDE; they don't modify the global X server settings. Some distributions may include other modules in this section, such as a Digital Camera module that lets you add and configure one or more digital cameras.

18.3.6.1 Keyboard

This module configures your primary keyboard layout and any additional layouts (if you work in more than one language, for example). Use it also to configure other keyboard options.

The Layout tab determines your keyboard layouts if you check "Enable keyboard layouts." In the Configuration section, three drop-down lists are available to set your keyboard model, primary country and language layout, and a primary variant. The options on the variant drop-down list vary depending on which primary layout you select, but generally include different keymaps for the same language.

In the "Additional layouts" section, select any other layouts you may want to use. You can also select a variant for each. The additional layouts include variations such as the Dvorak keyboard layout, in addition to language layouts. The list of layouts shows a flag image for each layout. When you enable layouts, a button is added to the system tray in the panel that allows you to switch between your selected layouts. The button contains the flag for the current layout. Click the flag to cycle through the layouts.

The Options tab sets the Switching Policy to one of Global, Window Class, or Window. The policy determines whether a layout switch happens globally, by window class, or on a window-by-window basis. The Xkb Options section sets Xkb (X keyboard) options; you can check the box Reset Old Options to reset your options to the defaults as defined in your /etc/X11/XF86Config file. The rest of this section consists of five drop-down lists used to set the behavior of certain keys.[2] Each can be left blank or set to one of the listed options. The drop-down lists are:

[2] Depending on your Linux distribution, you may not see all the lists described here.

CapsLock Key Behavior

Sets whether the Caps Lock key uses internal capitalization or acts as a shift lock key, in each case with or without canceling caps.

Third-Level Choosers

Sets the key or keys that can be used as an ISO 9995 third-level chooser. ISO 9995 is a multipart ISO standard that specifies keyboard layouts for text and office systems. The choices are Any of the Win-keys, Left Win-key, Right Control, Right Win-key, or Menu key.

Control Key Position

Determines the position of the Control key. The choices are Control Key at Bottom Left, Control Key at Left of "A", Make CapsLock an Additional Control, or Swap Control and CapsLock.

Use keyboard LED to show alternative group

Sets one of Scroll_Lock LED, Caps_Lock LED, or Num_Lock LED to show an alternative group as defined by ISO 9995.

Group Shift/Lock behavior

Determines what key is used to switch groups. Some of the options change the group until it is changed again, while others change the group only while the key is pressed. The choices are: Left Win-key changes group, Both Win-keys switch group while pressed, R-Alt switches group while pressed, Both Shift keys together change group, Right Win-key changes group, Left Win-key switches group while pressed, Caps Lock key changes group, Right Alt key changes group, or Alt+Shift changes group.

The Advanced tab configures the keyboard repeat (i.e., holding a key down repeats the character until you release the key). Check the "Keyboard repeat" box to enable keyboard repeat, and use the slider to set the keyclick volume. If you don't want to hear keyclicks, set the slider to 0. Note that your keyboard may not support changing the keyclick volume. The section "NumLock on KDE startup" determines the state of the NumLock key when KDE starts. Click Turn on, Turn off, or Leave unchanged.

18.3.6.2 Mouse

This module configures the movement and button layout of your mouse.

On the General tab, the Button Mapping section sets the mouse to be right-handed or left-handed. In the Icons section, select either "Single-click to open files and folders" or "Double-click to open files and folders." If you select single-click, you also have the option to check "Change pointer shape over icons" and "Automatically select icons." If you select "Automatically select icons," move the slider to determine how long the pointer can remain over the icon before it is selected. If you select double-click to open, then a single click selects an icon. Check "Visual feedback on activation" or "Large cursor" to select either of those options.

On the Advanced tab, the Pointer Acceleration slider determines how fast the pointer moves on your screen when you move your mouse. Lower values move the pointer more slowly for small mouse movements, giving you finer control. Higher values let you cross the screen more quickly. The Pointer Threshold slider sets the distance (in pixels) that the mouse must move before pointer movement occurs. The Double Click Interval slider sets the maximum time that can pass between two clicks and still be considered a double-click. The Drag Start Time slider sets the amount of time that has to pass after you click a button and start to move the mouse before it is considered a drag operation. The Drag Start Distance slider sets the distance (in pixels) that the mouse must move with a button clicked before it is considered a drag operation. The Mouse Wheel Scrolls By slider determines how many lines are scrolled for one mouse wheel movement.

18.3.7 Personalization

The Personalization modules cover configuration options that don't fit neatly into any of the other categories.

18.3.7.1 Accessibility

The Accessibility module sets configuration options to make the system more accessible. The Bell tab sets the audible bell to one of "Use System bell" or "Use customized bell." If you choose a customized bell, use the text box to enter the path to the sound you want, or select Browse. You can set a visible "bell" by checking "Use visible bell" and then either "Invert screen" or "Flash screen." Select a color by clicking the color button and use the slider to set the duration of the inversion or flashing.

The Keyboard tab has three settings to make the keyboard easier to use:

Use sticky keys

Pressing one of the Ctrl, Alt, or Shift keys and then releasing it to press another key is treated as a multi-key combination for the next keypress. For example, to enter Ctrl-Tab with sticky keys enabled, press Ctrl, release it, and then press Tab. You can also check "Lock sticky keys." In that case, pressing Ctrl, Alt, or Shift once behaves the same as "Use sticky keys"; pressing the key twice leaves it in the modified mode until you press it again to release it.

Use slow keys

Each key must be held down for the amount of time specified by the Delay slider to be recognized as a key press. This protects you from accidental keystrokes.

Use bounce keys

The amount of time specified by the Delay slider must pass between two key presses for the second one to be recognized. This protects you from accidentally hitting multiple keys if you type fast.

The Mouse tab sets values for using the arrow keys on the numeric keypad to move the mouse pointer instead of having to use a mouse, trackball, or other device. The possible settings are Acceleration Delay, Repeat Interval, Acceleration Time, Maximum Speed, and Acceleration Profile. If you don't have a numeric keypad (e.g., on a laptop computer), the numeric keypad keys are usually available on the keyboard, accessed with a function (fn) key.

18.3.7.2 Country & Language

The Country & Language module sets the preferred locale settings for your programs. The Locale tab has a drop-down list for selecting your country. When you select a country, the language or languages generally used in that country appear in the Languages box. You can add a language to the list from the Add Language drop-down list, or select a language and click Remove Language to remove one from the list. The bottom portion of the tab shows the default appearance of numbers, money, dates, and time for that country and language. Use the remaining tabs to change these defaults. As you change the settings, the examples at the bottom of the window (which are shown on all the tabs) also change, so you can see how they will look with the new settings.

The Numbers tab lets you set the character used for the decimal symbol, thousands separator, positive sign, and negative sign.

The Money tab lets you set the character to be used for the currency symbol, decimal symbol, thousands separator, and fract (fractional) digits, i.e., the number of digits after the decimal point. In the sections positive and negative, check the "Prefix currency symbol" box to have the currency symbol appear before the positive or negative sign, and then select where the sign should be placed from the drop-down list. The possible positions are:

Parentheses around

Display the value in parentheses. For example, you might select this option to display negative numbers in parentheses rather than showing a minus sign.

Before quantity money

Display the sign after the currency symbol and before the value.

After quantity money

Display the sign after the value and before the currency symbol.

Before money

Display the sign before both the value and the currency symbol.

After money

Display the sign after both the value and the currency symbol.

The Time & Dates tab has the following settings: Time format, Date format, Short date format, and Start week on Monday. Select the time and date formats from drop-down lists or enter a format into the appropriate text box. Check the "Start week on Monday" box if you want Monday rather than Sunday to start a new week. The time and date formats are specified with the following codes; the table shows the time codes first, then the date codes.

Code | Replaced by
HH | The two-digit hour on a 24-hour clock.
hH | The hour on a 24-hour clock, using one or two digits as appropriate.
PH | The two-digit hour on a 12-hour clock.
pH | The hour on a 12-hour clock, using one or two digits as appropriate.
MM | The minute, using two digits.
SS | The second, using two digits.
AMPM | Replaced with either "am" or "pm" as appropriate; primarily for use with a 12-hour clock setting.
YYYY | The four-digit year.
YY | The two-digit year.
MM | The two-digit month.
mM | The month, using one or two digits as appropriate.
MONTH | The full name of the month.
SHORTMONTH | The abbreviated name of the month.
DD | The two-digit day of the month.
dD | The day of the month, using one or two digits as appropriate.
WEEKDAY | The full day of the week.
SHORTWEEKDAY | The abbreviated day of the week.

18.3.7.3 Crypto

The Crypto module controls the configuration of the OpenSSL implementation of the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) network protocols. Use this module to configure SSL for use with KDE applications, and to manage your personal certificates and known certificate authorities. The module has six tabs: SSL, OpenSSL, Your Certificates, Authentication, Peer SSL Certificates, and SSL Signers.

If you do not have OpenSSL installed, each of the tabs displays the message "SSL ciphers cannot be configured because this module was not linked with OpenSSL." If you do have OpenSSL installed, you probably still should not make any configuration changes unless you are familiar with SSL and know what you are doing. For more information on using and configuring OpenSSL, see the O'Reilly book Network Security with Open SSL.

At the bottom of the SSL tab are some checkboxes. If OpenSSL is installed, you'll see five checkboxes; if it is not installed, only the last three are shown and available. The checkboxes are:

Use EGD

Use the entropy-gathering daemon (EGD) to initialize the pseudo-random number generator. Entropy is basically a measure of randomness; SSL requires random numbers for such functions as creating public and private keys, and EGD is a Perl script that gathers entropy.

Use entropy file

Use the file whose path you specify in the text box or by browsing as the source of entropy for the pseudo-random number generator.

Warn on leaving SSL mode

See a warning when you leave an SSL-enabled site.

Warn on sending unencrypted data

See a warning when you are about to send unencrypted data over the network with a web browser.

At the top of the SSL tab are three checkboxes that enable TLS support (if it's available), SSL v2 support, and SSL v3 support. These options are followed by two columns containing a list of SSL v2 and SSL v3 ciphers. You can check or uncheck the ciphers individually to select the ones you want to use, or use the buttons below the lists to select them in groups: Most Compatible, US Ciphers Only, Export Ciphers Only, or Enable All.

The OpenSSL tab lets you specify the path to your SSL libraries or use the Browse button to locate them. Then click on the Test button to test your settings.

The Your Certificates tab shows a list of certificates that KDE knows about and lets you manage them with a set of buttons on the right-hand side. The buttons are Import, Export, Remove, Unlock, Verify, and Change Password.

The Authentication tab lets you specify a default certificate from the drop-down button and a default action or policy. The possible policies are Send, Prompt, and Don't Send. You can also add or remove hosts and host certificates, and set one of the same three actions for each.

The Peer SSL Certificates tab lets you Export, Remove, or Verify peer organizations, and set a policy of Accept, Reject, or Prompt for each.

The SSL Signers tab lets you Import, Remove, or Restore organizations to a list of signing organizations, and determine whether to accept for site signing, accept for email signing, or accept for code signing.

18.3.7.4 Konsole

The Konsole module configures the Konsole terminal emulator. It has four tabs: General, Schema, Session, and Write Daemon.

The General tab has settings to determine general Konsole behavior:

Use Konsole as default terminal application

Set Konsole as your default terminal.

Show Terminal Size when Resizing

Display the number of characters and lines as you resize the terminal. The display changes as you change the size, showing the current dimensions.

Show Frame

Put a frame around the terminal window. If the frame is turned on, a narrow edge appears inside the Konsole window around the portion that represents the terminal itself. This option does not affect the border around the entire Konsole window.

Warn for Open Sessions on Quit

Konsole warns you if you still have open sessions when you quit out of Konsole.

Blinking Cursor

The cursor blinks inside the Konsole window, making the cursor easier to find.

Require Ctrl key for drag and drop

Require the use of the Ctrl key for dragging and dropping text. Konsole allows you to drag text and drop it into other applications.

Line Spacing

Use the up or down arrows to set the line spacing. The default value is Normal, which is single-spacing.

Double Click

The text box shows a default set of characters (besides letters and digits) that are treated as part of a word when you double-click to select a word. You can add or remove characters from this set.

The Schema tab sets up the appearance of the Konsole window. The Schema box in the center of the tab shows the available schemas with the current one highlighted. The current schema also is shown in the Title box at the top. Check the box under the list of schemas to set the highlighted one as the default or click the Remove Schema button to remove it from the list. You can also set up a color scheme and add a background image to your Konsole sessions.

The Session tab lets you set properties for the different types of Konsole sessions. Pick the session type from the list in the Session section of the tab, and then enter or change the name, the command to execute, and the default directory in the General section. You can select an icon by clicking on the image of the current icon, pick a font size from the Font drop-down menu, enter or change the setting of the TERM environment variable, set the keyboard type (e.g., Linux console, VT100, or XTerm), and set the color schema for that session type.

The Write Daemon tab has a single checkbox, whose effect is to start the write daemon when KDE starts up. You should generally leave this box checked.

18.3.7.5 Passwords

The Passwords module has three settings that determine how passwords are treated when you run privileged operations. Note that there are security implications to these settings. If you are not in a secure location, be careful of setting options that may make things easier for you but may also open security holes. The settings are:

Echo characters as

Determines if and how your password is echoed on the screen as you enter it. Each character can be shown as one star, three stars, or not at all.

Remember passwords

KDE will remember passwords so they don't have to be entered each time.

Timeout

If "Remember passwords" is checked, this option becomes available to set the period of time for the passwords to be remembered. For example, you might set a timeout period of an hour if you are temporarily doing work that requires superuser privileges.

18.3.7.6 Session Manager

The Session Manager module controls the configuration of your KDE sessions. Check the "Confirm logout" box if you want KDE to ask for confirmation before logging you out. The confirmation box lets you change your mind and cancel the logout, or proceed to log out, with or without saving your current session information. If you check the "Save session for future logins" box, the logout confirmation box will also have that option checked by default; you can uncheck it when you log out to have your next session revert to the previously saved session.

The section "Default action after logout" has three options that control what action takes place by default when you log out. Check one of: Login as Different User, Turn Off Computer, and Restart Computer. The default action applies only if you logged in through the kdm display manager. You can always choose a different option if you let the system prompt you for confirmation.

18.3.7.7 Spell Checking

The Spell Checking module configures the KDE spell checker, KSpell. You can check either or both of "Create root/affix combinations not in dictionary" and "Consider run-together words as spelling errors." Select a dictionary from the drop-down list of dictionaries available on your system; also select the language encoding to use from another drop-down list, and whether to use international ISpell or ASpell as the underlying spell-checking client program. International ISpell is an interactive spell-checking program that understands many European languages. ASpell is similar to ISpell, but it is smarter about suggesting alternative spellings.

18.3.8 Power Control

The Power Control modules configure the energy-saving and battery settings for your system. The Energy module applies to all systems that have a monitor with energy-saving capabilities; the remaining modules apply to laptop or other battery-powered systems using the Linux Advanced Power Management (APM) or Advanced Configuration and Power Interface (ACPI) features.

The Laptop Power Control module is available only if your system supports APM and you set the setuid bit for the APM binary file. (Do this as root with the command chmod u+s /usr/bin/apm. But be aware that there are security issues with turning on the setuid bit.) In addition, both the Low Battery Critical and Low Battery Warning modules add Suspend and Standby to the possible options if this file is setuid. Suspend mode is designed for times when you want to stop working (especially on a laptop), but want to be able to restart where you left off. Open applications are preserved in memory, the CPU remains active at a low level, and the hard drive is shut down. Standby mode shuts the computer down almost completely, but continues to draw a small amount of power so that it wakes up quickly when you restart it. Nothing is saved in memory.

18.3.8.1 Battery Monitor

Check the Show Battery Monitor box in the Battery Monitor module to turn on the visual display of the battery's status. Then you can set the frequency with which the status should be checked. You can also change the icons that appear when there is no battery, the battery is not charging, or the battery is plugged in and charging by clicking on the icon that you want to change and selecting a new one.

18.3.8.2 Energy

If your hardware supports power management, you can enable it by checking the Enable Display Energy Saving box in the Energy module. Then use the sliders to set the amount of idle time before the system goes to standby mode, then to suspend mode, and finally turns off.

18.3.8.3 Laptop Power Control

This module configures how and when the automatic power-down feature takes effect. You can set the behavior separately for Not Powered, when the computer is running off the battery, and Powered, when it is plugged into a power supply. For each case you can set it to suspend, go into standby mode, or turn off. Then set the amount of idle time before the power management takes effect. It's common to set a shorter delay for battery power to save the battery.

18.3.8.4 Low Battery Critical

The Low Battery Critical module sets a trigger time for notifying you that your battery is almost out of power. The time tells you how many minutes are left before the battery runs out of power. The remaining options determine what happens when that threshold is reached. The first two choices are Run Command and Play Sound. Each has a text box where you can enter the path to the command or the sound. The remaining options are System Beep, Notify, Suspend, and Standby. Suspend and standby are available only if /usr/bin/apm has the setuid bit on.

18.3.8.5 Low Battery Warning

The Low Battery Warning module is like the Low Battery Critical module, except that it notifies you sooner when the battery is running low. The trigger time is set to a higher number, so if both warnings are set, you will first get a warning that the power is getting low, and then the power-critical warning when it is about to run out. The other options are the same.

18.3.9 Sound

The modules contained in this section configure the keyboard bell and other system sounds. The basic modules described here are Midi, Sound Server, System Bell, and System Notifications. You may also have other Sound modules, such as Audio CD IO-Slave, which configures the program that lets you make .wav, .mp3, or Ogg Vorbis files from audio CDs or DVDs, or Mixer, which configures a sound mixer.

18.3.9.1 Midi

The Midi module sets the Midi device to use. Select the device you want from the list, and if you want to use a Midi map, check Use Midi Mapper and enter the path to the map file or click the Browse button to search for it.

18.3.9.2 Sound Server

The Sound Server module configures the aRts sound server, which is a simulation of an analog real-time synthesizer used by KDE for multimedia support. On the General tab, check "Start aRts soundserver on KDE startup" to enable the aRts server. This makes the rest of the checkboxes available:

Enable network transparency

Allow the server to respond to sound requests that come in over the network. Uncheck if you want the server to respond only to local requests.

Exchange security

Check this box if you also checked the "Enable network transparency" box. It allows security information to be exchanged across the network.

Run soundserver with realtime priority

If your system supports real-time scheduling, check this box to have the sound server run at a high priority. Note that you may need root privileges for this option to take effect.

Autosuspend if idle

The sound server will suspend itself if it has been idle for the number of seconds that you specify in the combination box. Having the server suspend itself frees the sound card for other applications.

Display messages using

Specify the application that will display aRts messages and enter the application to change it from the default artsmessage.

Whether or not you enable the sound server, you can set the level of messages to be displayed from the Message Display drop-down list. The choices are Errors, Warnings, Informational, and Debug. Messages at the selected level or higher are displayed.

The Sound I/O tab configures the sound itself if the sound server is enabled. Choose the Sound I/O method from the drop-down list. The choices are Autodetect, Threaded Open Sound System, No Audio Input/Output, and Open Sound System. The default Autodetect is usually fine. Similarly, you can set the Sound quality to Autodetect, 16 bits (high), or 8 bits (low). Between the two drop-down lists are four checkboxes: "Enable full duplex operation," "Use custom sound device," "Use custom sampling rate," and "Other custom options." Select full-duplex operation if you need to record and play sound at the same time. Use the custom options if you have particular requirements that make the defaults unsuitable. See the context-sensitive help to determine if you should check one of these boxes. The slider at the bottom of the tab labeled "Audio buffer size (response time)" determines how responsive the sound is. Moving the slider to the left speeds up response time, while moving it to the right slows it down. Faster response time has a cost, though, as it uses more of the CPU.

18.3.9.3 System Bell

This module configures the system bell. Checking "Use System Bell instead of System Notification" enables the other options, which you can set with sliders or directly in the combination boxes. Volume sets the volume of the bell, measured as a percentage of the maximum possible volume; Pitch sets the tone of the slider in Hz; and Duration determines how long the beep lasts, in milliseconds. To listen to your settings, click the Test button.

18.3.9.4 System Notifications

This module allows you to enable and configure sound events for different applications. Most of the window is taken up with a tree listing of applications and events. For each event, you can select among four choices for how you want to be notified:

Log to file

Log the event to a file, specified in the Filename text box below.

Play sound

Play the sound contained in the file specified in the Filename text box below. You can also check the box "Use external player" to use a particular media player and enter the path to the player in the text box.

Show messagebox

Display the notification in a message box displayed in the program's window.

Standard error output

Write the message to the standard error output.

You can select more than one option. For example, you might want to hear a sound and also have the event logged to a file.

The volume slider lets you determine the sound volume, and the long button at the bottom of the window switches between "Enable all sounds" and "Disable all sounds" to turn sound on or off for all applications at once.

18.3.10 System

The system modules set configuration options that have a systemwide effect. For that reason, most of them require you to enter the root password before you can make changes. Other modules, like the Font Installer module, let you make changes in your home directory without the root password, but require it for global changes. To enter the root password, click the Administrator Mode button in the lower-right corner of the window and enter the password in the window that appears. A red border appears around the module window to indicate that you are in administrator mode. Administrator mode does not carry over across modules. You must enter the root password for each module you want to use in administrator mode.

In addition to the modules described here, other modules that you might find depending on your distribution and KDE version include Boot Manager (LILO), Linux Kernel Configurator, Alarm Daemon, and XML RPC Daemon.

18.3.10.1 Date & Time

The Date & Time module lets you set the system date and time. The window has a calendar in the upper left corner of the window, and a clock in the upper right. Set the date by selecting a month from the drop-down list and setting the year in the combination box. Then select the correct date from the calendar. Set the time by entering the correct hour, minutes, and seconds in the boxes under the clock. The current time zone is displayed under the clock; you can choose a new time zone by selecting a location from the drop-down list and click Apply to see the new time zone displayed.

18.3.10.2 Font Installer

The Font Installer module installs new fonts onto the system. If you want to install a font globally, click the Administrator Mode button and enter the root password; otherwise the font will be installed in your home directory. The two columns on the Fonts tab show the directory from which the font will be installed on the left and the directory to which it will be installed on the right. To install the font from a different location, click the Change Folder button and select a new location. If you highlight a font in one of the columns, a preview appears in the box at the bottom of the window. To install a font, select it from the first column and click the Install button.

The Anti-Alias tab lets you set up options for antialiasing with the XRender Extension. If your system is not capable of using this extension, the checkboxes under the Configuration File text box are grayed out. If they are available, you can check "Exclude range" and enter the end points of the range to exclude certain point sizes from antialiasing, and check "Use sub-pixel hinting."

If you are in administrator mode, you can click the Advanced button to set up rules for matching font families and establish any desired include directives specifying additional font files. The Include Directives tab has two sections. Any files listed in the top section, Include, must be available. Files in the bottom section, Include If, are included if they are found, but aren't required.

The Settings tab has customization settings for five aspects of font installation:

Appearance

The Appearance settings customize the look and operation of the Font Installer module. The settings are:

Mode

Select Advanced or Basic mode. In advanced mode, the full font directory and file hierarchy are shown in the columns on the Fonts tab, and you can install Speedo and bitmap fonts in addition to TrueType and Type 1. In basic mode, only the font files are shown in the columns on the Fonts tab, and you can install only TrueType and Type 1 fonts.

Font Lists

Select whether to display the fonts on the Fonts tab in left and right columns or top and bottom columns.

Custom preview string

Check this box and enter the string if you want to see characters other than the alphabet for the font preview on the Fonts tab.

Folder & Files

When you select the Font Installer module, it searches for the correct folders (directories) and files. Use these settings to make any changes or add any missing entries for the fonts folder, the font configuration file, and the encodings folder. You can also check the Ghostscript, Fontmap file box and set the path to the file to enable configuration of Ghostscript. Check the CUPS folder box and set the path if you are using CUPS (the Common Unix Print System) and want to enable its configuration.

Install/Uninstall

To configure font install and uninstall operations, check "Fix TrueType Postscript names table" to automatically fix the names table when you install TrueType fonts; this corrects any problems that sometimes occur with TrueType fonts. You can also specify a file to which fonts should be moved when they are uninstalled.

StarOffice

Check the box to configure fonts for StarOffice, and specify a folder and a printer file. These options need to be set only for versions of StarOffice before Version 6. OpenOffice and later versions of StarOffice don't need this section.

X System

This section sets some X Window System font configuration options:

Configure X to only use ... encoding

Check this box and select an encoding from the drop-down list to specify an encoding for X to use.

Generate AFMs, with ... encoding

Check this box and select an encoding from the drop-down list to generate the Adobe Font Metric (AFM) files used by programs such as StarOffice to display font sizes correctly.

Command to Refresh X's Font List

This section lets you select the command to use after adding or removing fonts to refresh the internal font list. The choices are:

  • xset fp rehash: This command resets the font path, which causes the font server to reread its database.

  • /etc/rc.d/init.d/xfs restart: This command restarts the X font server. You must be in administrator mode to use this command.

  • Custom: Check this box to use a command of your own choosing, and enter the command in the text box.

18.3.10.3 Login Manager

The KDE login manager, kdm (KDE display manager), is the program that controls the graphical login screen. This module lets you configure the graphical style of the login screen and set some default display options, such as prelisted users and available session environments.

The Appearance tab lets you edit the greeting string displayed on the login screen. Certain special characters, such as %s and %n in the default greeting string, can be used; they are replaced as follows:

Sequence | Replaced by
%d | The current display
%h | The host name
%m | The machine (hardware) type
%n | The node name
%r | The operating system version
%s | The operating system
%% | A single %

You can choose a logo if you want one, or select Show Clock to display a clock instead of a logo. To select a logo other than the default KDE logo, click the logo image and select another image file. A drop-down list offers you a choice of GUI styles for the login screen. Use the Echo Mode drop-down list to choose whether to replace each character of the password with a single star, three stars, or no echo. The Language option lets you select the default character encoding for kdm.

The Fonts tab lets you choose the font style and size for the Greeting, Fail, and Standard screen messages. Select which type you want to configure from the drop-down list and click the Change Font button. The pop-up window shows a list of available fonts and lets you set the point size. Click the OK button to close the pop-up window. The font you have chosen is displayed in the Example area of the tab.

The Background tab lets you select the background for the login screen. See the earlier description of the Background module in the Look & Feel section for a detailed description of the options on this tab.

The Sessions tab configures session settings. There are two drop-down lists at the top that set who is allowed to shut down the system from the console and remotely. The choices for both are Everybody, Only root, and Nobody. The default for the console is Everybody; the default for remote shutdown is Only root.

The Commands section allows you to set the commands used for shutdown and restart. In the Lilo section, check "Show boot options" to enable the LILO boot options to be displayed in the Shutdown menu. The Session Types section configures the list of session types available to the user from the login screen. The Default list contains the various environments that are installed on your system, such as KDE and GNOME. You can add a new type or remove a type from the listing.

The Users tab lets you show a list of users on the login screen. The users are listed by username with a logo displayed for each user. To log in, you can simply click your logo to automatically enter your name into the login box, but you still must supply your password. The tab contains listings labeled "Remaining users," "Selected users," and "No-show users." You can select names from the lists and use the arrow buttons to move them from one box to another. Two options are available for who to display on the login screen. You can place names in the "Selected users" list and click the "Show only selected users" button, or you can click the "All but no-show" button to display users in both the "Remaining users" and "Selected users" lists. No-show users are user IDs that are used to control access-restricted system resources (e.g., root, news, and nobody). They are never displayed on the login screen. You can add the names of other users to the no-show list. Check the "Sort users" box to display the images in alphabetical order.

You can select a different default image by clicking on the image button and choosing another image file. You can also select a unique image for each user by highlighting the user in one of the lists and selecting an image file for that user.

Users whose image is not shown on the login screen can still log in; the only difference is that they have to enter their login name as well as their password.

The Convenience tab offers options that make logging in easier and more automatic. The drawback to the convenience options is that they are potential security risks, because they make it easy for someone without a valid login ID to access the system. Therefore, conveneince options should be used only on a system that is in a secure environment. The sections on the Convenience tab are:

Automatic login

If you check the box "Enable auto-login" in this section, you log in normally to KDE, but if you then use Ctrl-Alt-Backspace to kill the X server, kdm will log you in automatically when it comes up again. If you check the box "Truly automatic login" and select a username from the drop-down box, kdm will automatically log you in to that account when it comes up.

Preselect User

kdm can be configured to start up with a username already entered in the Name field. Select None if you do not want this option, Previous to have the previously logged-in user preselected, or Specify to choose a user from the drop-down list. Check the Focus password box to leave the cursor in the password field after preselecting the user. The alternative is to leave it in the user box so you can select a different username.

Password-less login

Check the "Enable password-less logins" box if you want users to be able to log in without entering a password. Then move users from the "Password required" list to the "Skip password" list, to identify users who can log in without entering their password.

Miscellaneous

Check the box "Automatically log in again after X server crash" to have kdm log you in automatically when X restarts after a crash.

18.3.10.4 Printing Manager

The Printing Manager module configures the KDE print manager, KDEPrint. KDEPrint is a frontend to your system's printing subsystem that provides an interface layer between KDE applications and the printing subsystem. Therefore, the details for using the Printing Manager module may vary depending on the printing subsystem in use.

Any application can use KDEPrint by printing to $KDEDIR/bin/kprinter instead of /usr/bin/lpr. KDEPrint supports all the usual Linux printing subsystems, with an emphasis on CUPS.

The configuration window has a row of icons on the top. If you select Administrator Mode for this module, all the icons are available except for features you don't have installed. Otherwise, you can select only certain icons. From left to right, the icons are:

  • Add printer/class

  • Add special (pseudo) printer

  • Start/Stop printer

  • Enable/Disable job spooling

  • Set as local default

  • Set as user default

  • Remove

  • Configure

  • Test printer

  • Printer tools

  • Restart server

  • Configure server

  • Configure manager

  • Refresh view

  • Show/Hide printer details

  • View

  • Orientation

  • Toggle printer filtering

Below the icons is a large window that lists all available printers or pseudo-printers. A pseudo-printer lets you send print output somewhere other than to a printer, such as a file or a fax. At the bottom of the window is a drop-down list of print systems that shows the print system in use. Below that is a window with four tabs. The tabs provide detailed information for the printer currently highlighted in the printer list. The Information tab shows information such as the type, state, and location of the printer. The Jobs tab lists current jobs and their status. The Properties tab displays current property settings and lets you change them. The Instances tab shows individual printers and lets you configure them.

18.3.11 Web Browsing

The Web Browsing modules let you configure the Konqueror web browser.

18.3.11.1 Cache

The Cache module controls the use of a local cache to save copies of web pages you have visited. Using a cache lets Konqueror display pages without going back to the remote web site, which saves time and Internet access at the cost of using disk space and not always seeing the current version of a page. If you use the cache, you can always press Konqueror's Reload button to get the latest version.

The Use Cache button is checked by default. Uncheck it if you do not want any pages stored in a cache on your system. The Policy section controls how up to date the cache is kept and whether to read first from the cache or the Web. Check one of these options:

Keep cache in sync

Before displaying a page from the cache, verify that it is still valid and, if not, reread it from the remote site.

Use cache if possible

Display a page from the cache if it is there, otherwise read it from the remote site.

Offline browsing mode

Display a page from the cache if it is there, otherwise do not display it. Do not attempt to reread the page from the remote site.

In the "Disk cache size" box, enter the cache size you want. Click the Clear Cache button at any time to empty the cache.

18.3.11.2 Cookies

The Cookies module sets Konqueror's cookie policy and lets you manage individual cookies. This module has two tabs: Policy and Management.

On the Policy tab, check the Enable Cookies box to enable web sites to store cookies on your system. Then check one of the options in the Default Policy section:

Ask for confirmation before accepting cookies

Konqueror asks you to confirm your acceptance of every cookie. Each time a web site wants to store a cookie, a window pops up asking if you want to accept the cookie. At that time, you can choose to apply your response to just that cookie, all cookies from the domain, or all cookies.

Accept all cookies by default

Konqueror accepts and stores all cookies. If you select this policy, you will never be asked for confirmation. You can go to the Management tab later to remove cookies you don't want.

Reject all cookies by default

Konqueror refuses to accept any cookies. Selecting this policy can result in your not being able to use certain web sites that require you to accept their cookies. You can change this policy later for all cookies or for a particular domain.

The Domain Specific Policy section lets you override the default policy for cookies from certain domains. This section lists domains for which you have specifically chosen to accept or reject cookies. Click the New button to add a domain. Click on a domain in the list to change the policy for that domain or to delete it from the list. The Delete All button deletes the entire list. The possible policies are Accept, Reject, and Ask.

The Management tab lets you manage cookies stored by Konqueror. The top portion lists the cookies hierarchically by domain and host. Select a domain and click Delete to delete all cookies from that domain, or select an individual cookie from the Host column and click Delete to delete just that cookie. If an individual cookie is selected, the Cookie Details portion of the tab shows the content, expiration date, and other information for that cookie. The Delete All button deletes all cookies stored by Konqueror, and the Reload List button reloads the list of stored cookies if more have been saved since you selected this module.

18.3.11.3 Enhanced Browsing

The Enhanced Browsing module controls the use of Internet keywords and web shortcuts by Konqueror—two features designed to make web browsing easier. Click the Enable Internet Keywords box to enable the use of Internet keywords. This lets you enter words such as company names without having to enter a full URL. For example, the use of Internet keywords would let you enter oreilly instead of the full URL http://www.oreilly.com. If you enable Internet keywords, you can also use the Fallback Search Engine drop-down list to pick the search engine to use if what you entered isn't found as an Internet keyword.

Check the Enable Web Shortcuts box to enable the use of web shortcuts. These are shortcuts that are not known Internet keywords, but have much the same purpose. A predefined list of shortcuts is provided. For example, gg is a shortcut for Google. This means that you can enter gg:KDE anywhere a URL is expected, and KDE searches Google for references to KDE. You can add your own shortcuts by clicking Add, or select an entry in the list and click Change to change its associated shortcuts or Delete to remove it from the list. The character sequence \{@} in a shortcut causes the shortcut to prompt the user for a string (such as a term in a query) and to plug the user's string into the shortcut at that point.

18.3.11.4 Konqueror Browser

This module configures settings used for Konqueror's web browsing functionality. It has five tabs: HTML, Appearance, Java, JavaScript, and Plugins.

On the HTML tab, checking the box "Enable completion of forms" causes Konqueror to store your responses as you fill in forms and automatically fill in the same information in other forms. Move the "Maximum completions" slider to set the maximum number of responses Konqueror will remember. Check the box "Change cursor over links" to have Konqueror display a different cursor when the pointer is over a link. The link cursor is a hand with a finger pointing to the link. If you check the box "Right click goes back in history," right-clicking on a web page acts like the Back button and takes you back a page. Check the box "Automatically load images" to have Konqueror load embedded images as it loads a web page. Check the box "Allow automatic delayed reloading/redirecting" to allow Konqueror to honor reload or redirect requests from the remote host. Choose an option from the Underline Links drop-down box to determine if and when links should be underlined. Select Enable to always underline links, Disable to never underline them, or Only on Hover to underline links only when the mouse pointer is directly over the link. Finally, you can enable or disable animations, or set them to be shown only once.

The Appearance tab sets fonts, font sizes, and the default encoding. Use the top slider to set the minimum font size and the lower slider to set the medium font size. Then specify your preferred fonts. The text boxes let you set standard, fixed, serif, sans serif, cursive, and fantasy fonts. Use the Default Encoding drop-down box to set the default language encoding. Just above this box, you can set a font size adjustment for the encoding.

The Java tab controls whether you will permit web pages to run Java applets. This tab lets you turn Java on globally, or set a policy on a host- or domain-specific basis. You can also turn Java on globally and then selectively turn it off for certain hosts or domains. To set policy by domain, click the Add button to specify a domain. A dialog box appears for you to enter the host or domain name and specify a policy of Reject or Accept. If you change your mind, you can click the Change or Delete button to change the policy or delete the entry. If you enable Java globally, you can also set the following Java Runtime Settings.

Show Java Console

Open a Java console window for the use of Java applets.

Use Security Manager

Run a security manager that prevents Java applets from accessing your filesystem or perfoming other insecure actions. Normally, you should leave this box checked to protect your system.

Shutdown Applet Server when inactive

Shut down the Java Applet Server when no Java applet is running. This frees up resources when no applet is running, but causes a new applet to take slightly longer to start. If you choose this option, you can also move the Applet Server Timeout slider to set the number of seconds with no applet activity before the server shuts down.

Path to java executable, or "java"

Enter the path to the Java executable in the text box, or java to have Konqueror find Java in your path.

Additional Java Arguments

Enter any arguments for the Java virtual machine in this text box.

KDE does not implement any Java functionality itself; it relies on an external Java virtual machine. Therefore, you must already have Java installed on your system in order for these settings to have any effect.

The JavaScript tab controls whether you will permit web pages to run JavaScript code. Check the box to enable JavaScript globally, or set a policy on a host- or domain-specific basis, as you did for Java. As with Java, you can turn JavaScript on globally and off selectively for certain hosts or domains. Finally, set the policy you want for JavaScript web pop-ups. The possible policies are:

Allow

Allow all JavaScript pop-ups.

Ask

Ask for permission before displaying a JavaScript pop-up.

Deny

Don't allow any JavaScript pop-ups.

Smart

Allow only JavaScript pop-ups that have been activated by the user with a mouse click or keyboard operation.

On the Plugins tab, check Enable Plugins Globally to allow the use of plug-ins.

18.3.11.5 Netscape Plugins

The Konqueror browser can use Netscape plug-ins to display various types of web content. The Netscape Plugins module lets you tell Konqueror where to find the plug-ins on the system.

The Scan tab contains a list of directories for Konqueror to scan when looking for Netscape plug-ins. Initially, it contains a list of directories where plug-ins are typically found. You can add or delete entries from the list with the New and Remove buttons, or move around in the list with the Up and Down buttons. Or you can simply click on the entry you want with the first mouse button. Click the Scan for New Plugins button to have Konqueror rescan the directories in the list. You can also check the box labeled "Scan for new plugins at KDE startup" to run the scan each time KDE starts.

The Plugins tab contains a list of plug-ins that Konqueror found when it scanned the directories listed on the Scan tab. Check the box labeled "Use artsdsp to pipe plugin sound through aRts" if you want to use the analog real-time synthesizer to play sound.

18.3.11.6 Proxy

If your system is behind a firewall, you may need to use a proxy server for HTTP and FTP services. The Proxy module lets you enable the use of a proxy and configure it. Check the Use Proxy box to enable the use of a proxy server. The remaining options are:

Automatically detected script file

Konqueror will automatically find the setup configuration script file.

Specified script file

Specify the location of the script file, and enter the path to the file in the Location text box.

Preset environment variables

Check this box if your system has preset environment variables such as $HTTP_PROXY for graphical and nongraphical applications to share proxy configuration information, and click the Setup button to provide the environment variable names.

Manually specified settings

Provide the proxy server locations manually, and click the Setup button to provide the information.

Prompt as needed

Konqueror will prompt as needed for login information.

Use automatic login

Check this box if you have login information set up for your proxy server in the file $KDEHOME/share/config/kionetrc.

18.3.11.7 Stylesheets

The Stylesheets module contains settings for the use of CSS (Cascading Style Sheets) in Konqueror. On the General tab, choose the stylesheet. Check "Use default stylesheet" to use the Konqueror default; check "Use user-defined stylesheet" to specify a different stylesheet, and enter the path to the stylesheet in the text box. Or check "Use accessibility stylesheet defined in `Customize' tab" and go to the Customize tab to define the stylesheet.

On the Customize tab, select a font family and check the box if you want to use that family for all text, overriding custom font settings. Select a base font size and check the box if you want to use that font size for all elements, overriding custom font size settings. Select a color scheme: Black on White, White on Black, or Custom. If you select Custom, also select a background and foreground color by clicking on the Background and Foreground color buttons. You can use the same color for all text, overriding any custom color settings. Check the box "Suppress images" if you don't want any images automatically displayed, "Suppress background images" to prevent display of background images. Click the Preview button to see the effect of your choices.

18.3.11.8 User Agent

The User Agent module allows you to specify the user-agent string reported by the browser for sites that may not recognize Konqueror, or anything that's not a major commercial web browser. Check the box "Send browser identification" to send information about your browser; it is recommended that you leave this checked for the use of host sites that customize the page they send depending on the browser. The user-agent string contains the name and version number of the client program making the request. The default for Konqueror at the time of this writing is "Mozilla/5.0(compatible;Konqueror/3)". Check the boxes below the default identification to customize the information sent; the example is updated to reflect your choices. The options are:

Add operating system name

Adds the name of your operating system to the identification; e.g., Linux.

Add operating system version

If you checked the box to add the operating system name, you can also check this box to add the version.

Add platform name

Adds the name of your platform; e.g., X11.

Add machine (processor) type

Adds information about your processor; e.g., i586.

Add your language setting

Adds your language; e.g., en_US.

You can set the identification string individually for certain hosts or domains by clicking the New button. Enter the host or domain name in the dialog box that opens, and select the identity from the drop-down box. A description appears in the Alias box. Click the OK button to add the entry to the list. The Update list box updates the list of identities that are shown in the drop-down list. You can also change and delete individual entries in the list, or delete all of them at once with the Delete All button.


Chapter 19. An Alternative Window Manager: fvwm2

Among the most appealing characteristics of a Linux system are its flexibility, its independence from industry-dominating standards, and the degree of control a user has over his own working environment. Most flavors of Linux come with a default desktop environment replete with handy tools and menus and a consistent look and feel. The most widely used of these desktop environments are GNOME and KDE, the customization of which are detailed in Chapter 17 and Chapter 18, respectively. Both of these environments put a PC-like wrapper around what is basically a no-frills Unix-based system suitable for personal computers. For some people this is a good thing. But if you want a basic, functional desktop, and you're comfortable editing configuration files to customize your environment, you might instead try the fvwm2 window manager.

fvwm2 is the latest generation of a window manager called fvwm. fvwm predates both GNOME and KDE as a program that can provide multiple virtual screens to expand your desktop real estate. The letters vwm stand for virtual window manager, but the original meaning of the f has been forgotten and has led to much speculation. In fact, among the latest group of the program's developers are a number of cat lovers who claim the f stands for feline.

The first important concept you should understand in order to work with fvwm2 is that your desktop can be larger than the area of your screen. In fact, fvwm2 allows you to have acres of desktop real estate in the form of virtual screens, or pages. In a typical default environment, you might have a single desktop composed of four virtual screens/pages arranged in a two-by-two grid.

You can run applications on any of the screen pages you want and navigate the entire desktop in a variety of ways. If the default environment doesn't suit you, you can specify a grid of any size you like. How about three screens across and two down? No problem.

And if that still isn't enough space for you, you can also have multiple desktops, each composed of multiple pages. You might use separate desktops for different applications or different projects. fvwm2 provides the tools to navigate whatever space you design.

fvwm2 is also customizable in a vast number of other ways; the most significant are summarized in this chapter. What it all boils down to is maximum workspace and maximum flexibility.


19.1 Running fvwm2

Your Linux distribution may include a reasonably current version of fvwm2; if not, you can download it from http://www.fvwm.org. If you're running GNOME or KDE, the easiest way to switch over to fvwm2 is to edit your X client's startup file to invoke the window manager and then restart X. If you start X from the Linux command line with the startx command, the startup file is .xinitrc; if you start X from one of the graphical display managers (XDM, GDM, or KDM) and you are running Red Hat Linux, the file is probably .Xclients; otherwise, it is .xsession.

Here is an excerpt from a simple startup file that has been edited to run fvwm2:

xterm -geometry +50+0 &

xterm -geometry -0+0&

exec fvwm2

fvwm2 provides GNOME support as a compile-time option. As this is being written, the current stable version of fvwm2 is 2.4.15. The next major release, currently in development as the 2.5 series, will also support KDE compliance. In addition, fvwm2 now supports Xinerama as a compile-time option. Xinerama is a feature of recent versions of XFree86 that permits multiple monitors to be treated logically as a single monitor (of course, each of these monitors needs its own video card).

19.1.1 Configuration Files

The key to how fvwm2 works is the configuration file it reads at startup or restart. The systemwide configuration file is called system.fvwm2rc and usually lives in the directory /etc/X11/fvwm2. The typical system.fvwm2rc file that gets distributed should create a simple but perfectly workable environment. We'll take a look at one in the next section. There's no guarantee that the file on your system will create the same layout, but you'll get the idea.

If you want to customize fvwm2 to suit your needs, you need to make a copy of system.fvwm2rc called .fvwm2rc and put it in your home directory. This personal configuration file takes precedence over the systemwide file. You can edit your .fvwm2rc file to adapt the window manager to your needs.

There are a few simple rules for editing your .fvwm2rc file. First, any line that begins with a pound sign (#) is a comment (i.e., is not interpreted as part of the window manager definition). Second, a plus sign (+) at the beginning of a line means to repeat the first terms from the previous line. Section 19.5.2, later in this chapter, illustrates the use of this syntax. The final thing to keep in mind is that life will be simpler if you weave your own definitions into the file, respecting its current contents and their order. So, for instance, if you decide to define some function keys, put your new lines in the section of the file that already deals with keys.

In terms of fvwm2 customization, there's some good news and some bad news. The good news is that you can make an extraordinary number of changes to the way fvwm2 looks and operates. That's also the bad news. The window manager has dozens of configuration options, many very handy and easy to use, others complex and even arcane. The sum total can make the configuration file syntax daunting to anyone who isn't accustomed to serious tinkering. In fact, you could get dizzy considering the possibilities.

The fvwm2 manpage gives all the configuration options and illustrates their use; you may also want to consult the manpages for the fvwm2 modules, introduced in the next section. The web site http://www.fvwm.org is the definitive source for fvwm2 documentation, news, source code, and updates.

This chapter will help you cut to the chase in performing some of the more basic and useful customizations, as well as some tricky but handy upgrades.

19.1.2 A Modular Approach

fvwm2 has been designed to allow the interested user to devise new components, known as modules. A typical module is the Pager (FvwmPager), which provides a map of the desktop space and a way to navigate it, as we'll see a little later in the chapter. The Pager is a default module in just about any desktop environment.

FvwmWinList is another useful module. Though not as ubiquitous as the Pager, it is just as useful. The module displays the WinList, which is a small window that provides a list of all the windows running on all pages of all desktops. The WinList is another navigation tool, allowing you to switch the pointer focus to any application you have running and switch the screen view so that you can use that application. We'll talk more about this later.

A module is actually a separate program from fvwm2 but works in concert with it, passing commands to be executed to the window manager. Most configurations of fvwm2 have a Root menu with an FvwmModules submenu from which you can start certain of these programs. (Naturally, the list of modules on the menu is configurable.) You might also edit your .fvwm2rc file to run modules in other ways (when you type certain keys, when other events happen, etc.).

Since a module is a separate program, users can write their own modules without adversely affecting fvwm2. Note, however, that you must configure fvwm2 to start the module's process; you cannot start a module from the command line. Note also that while some modules, like the Pager, are intended to be used for the entire session, others simply perform a function and exit (e.g., RefreshWindow). Since modules are programs in their own right, many of them have their own manpages too.


19.2 Implementing Window Manager Customizations

If you edit your .fvwm2rc file, simply restart fvwm2 to have the changes implemented. In most environments, there will be a menu item that restarts the window manager. The vanilla setup we started with offers the item Exit Fvwm on the Root menu. If you select that item, you'll get a submenu titled Really Quit Fvwm? that contains several entries, including Restart Fvwm. When you select Restart Fvwm, your configuration changes should be implemented. A slower but just as effective way is to quit the X session and start it again (presuming your session startup file includes fvwm2).

19.2.1 A Quick Tour of the fvwm2 Environment

In any desktop environment with multiple virtual screens/pages, you can work on only a single screenful at a time. But fvwm2 makes it easy to run applications on different pages, move applications between pages, and switch the view between pages. If you refer to a particular window all the time, you can even arrange for it to appear on every page of every desktop. (We'll come back to this concept of "sticky" windows.) And you're not limited to viewing a page proper or keeping a window entirely on a single page.

Figure 19-1 shows an example of a typical fvwm2 environment. Notice the long horizontal box in the bottom right corner of the figure. This box is the FvwmButtons module (also called the button bar). FvwmButtons is generally used to house a number of tools and applications to which the user needs frequent access. Often these are other fvwm2 modules.

Figure 19-1. A typical fvwm2 environment

In this sample configuration, FvwmButtons contains two other modules: the Icon Manager (FvwmIconMan) on the left, and the Pager (FvwmPager) in the middle. At the far right you can also see three small application windows: xbiff (a mailbox that indicates when you have new email messages), xclock, and xload (a graphic representation of your system's workload).

The Icon Manager and the Pager are tools that let you monitor what's happening in your environment and manipulate the windows running there. The Icon Manager shows an entry for every conventional window currently on your display. If that window is iconified, the Icon Manager entry is preceded by a square that has a three-dimensional appearance. You can iconify and deiconify any window on the current page by clicking the first pointer button on the corresponding entry in the Icon Manager. (The Icon Manager always shows the windows on the current page; for a similar tool that reflects what's running on every page on every desktop, check out the WinList, described later in this chapter.)

Think of the Pager as a tiny mirror of your entire desktop(s). In a typical default environment with a single desktop composed of two-by-two screen pages, the Pager shows a small grid of four partitions separated by dotted lines. These partitions correspond to the desktop's four virtual screen pages. (If you configure for multiple desktops, a solid line is used to show the border between desktops. Section 19.2.5 later in this chapter tells you how to set this up.)

Each application you run appears in miniature in the Pager window. Applications with small windows are fairly hard to spot in miniature, but a blip representing them is there if you look closely. The miniature version of a larger client, like xterm, should have a readable label.

Whatever operations you perform on windows on the desktop (move, iconify, resize, and so on) are mirrored in the Pager. But the Pager is more than a monitor of activity—it's also a tool. Thus, you can move the miniature versions by clicking the second pointer button and dragging, and the actual windows will be moved. The Pager can also help you move windows between pages and desktops and select the area to be displayed on your monitor (which does not have to correspond to a page proper). You can select an area by right-clicking on the pager.

In addition to the desktop tools, fvwm2 is commonly configured to provide a set of cascading menus beginning from the Root menu. Click the first pointer button on the root window to reveal the Root menu. The Root menu is usually a good way to start a new terminal emulator window. If you start with the default environment for your system, the Root menu is likely to have submenus like Fvwm Modules, Fvwm Window Ops (which offers items like moving, resizing, and closing windows), Fvwm Simple Config Ops (for changing focus policies, how paging works, etc.), and Exit Fvwm (for restarting or exiting the window manager, starting another one, etc.).

This chapter assumes you know how to perform basic window manager operations. We're not going to teach you how to use the Pager or all the menu items. But we will show you how to change the number of desktops the Pager shows, add menu items, configure keyboard shortcuts, and make other useful customizations.

19.2.2 Specifying Click-to-Type Focus

Most versions of fvwm2 are configured to use the pointer focus model (FocusFollowsMouse or MouseFocus in the configuration file). This means you need to move the pointer into a window in order to type in it, post an application menu, and so forth. However, fvwm2 provides other options.

Two other focus policies are available: click-to-type focus (ClickToFocus), which requires you to click the pointer on the window in order to type in it, and the very handy SloppyFocus, which is like pointer focus with a twist—the focus does not leave the last window that had it until you move it into another window that takes over the focus. This can come in handy, particularly with terminal emulator windows like xterm and rxvt. You can actually move the pointer out of the way—accidentally or on purpose—and still continue to type in the window.

The best part of fvwm2's way of handling focus policy is that you can mix and match what windows use what type of focus. All the settings for focus policy are used as arguments to the Style variable. (Style takes several arguments that determine the appearance and behavior of a particular client or window manager component. See Style on the fvwm2 manpage for more information about this versatile option.)

In the following excerpt from a configuration file, the first line makes pointer focus the default for all applications (the asterisk is a wildcard). The subsequent lines specify the exceptions to this rule. The button bar works better with click-to-type focus, as do xman (the manpage viewer) and xmag (a magnification tool). The two terminal emulators benefit from sloppy focus.

Style "*"           FocusFollowsMouse

Style "FvwmButtons" Icon toolbox.xpm, ClickToFocus

Style "xman"        Icon xman.xpm, RandomPlacement, ClickToFocus

Style "xmag"        Icon mag_glass.xpm, RandomPlacement, ClickToFocus

Style "XTerm"       Icon xterm.xpm, SloppyFocus, IconBox -70 1 -1 -140

Style "rxvt"        Icon term.xpm, SloppyFocus, IconBox -70 1 -1 -140

In our sample configuration, the Simple Config Ops submenu of the Root menu offers three items that let you change the focus policy on the fly for the current window manager session: Sloppy Focus, Click to Focus, and Focus Follows Mouse. Note, however, that these items supersede what's in your configuration file for all applications. If you want to recover the more specialized definitions in your configuration file, you'll have to restart the window manager.

19.2.3 Raising the Focus Window Automatically

If you're using pointer focus (FocusFollowsMouse), you might want to consider also using the FvwmAuto module to automatically raise the focus window to the top. If we add the following line to our .fvwm2rc file, the focus window is automatically raised after the pointer has been in it for 200 milliseconds (one-fifth of a second):

Module FvwmAuto 200

The delay is important and makes FvwmAuto much more practical. When pointer focus is in effect, an autoraise feature can make the display seem chaotic: when you move the pointer across the screen, the focus hits several windows and they are raised in a distracting shuffle. With an autoraise delay, you can avoid the shuffling by moving the pointer quickly to the window you want to focus on.

If you use ClickToFocus mode by default, the autoraise feature is built in and you don't have to make this modification.

Of course, those who adapt to using the FvwmWinList module to transfer focus will have their windows raised automatically, without having to edit their .fvwm2rc file or even move the pointer off the WinList.

One of your menus may also be configured to offer an item that turns on autoraise on the fly and another item that turns it off again. In some default setups, the Fvwm Modules menu features AutoRaise and Stop AutoRaise for these purposes.

19.2.4 Changing the Size of the Desktop

Many default configuration files have a default desktop of two screen pages across by two screen pages down, which in the configuration file is defined using the line:

DeskTopSize 2x2

It's easy to change the size of your desktop by editing the dimensions of the grid. Thus, the following line creates a desktop of three pages across by two pages down:

DeskTopSize 3x2

You don't have to have multiple pages in both directions. You can have a desktop of one page above another above another:

DeskTopSize 1x3

You don't even have to have multiple pages at all:

DeskTopSize 1x1

But then why use fvwm2?

Of course, the number of pages you select will depend on your space needs and style of working and whether you will use more than one desktop (described in the next section). If you configure for multiple desktops, each one will have the same DeskTopSize. So if you want a desktop for work and one for play, you may not need each one to have many pages. Two desktops of three-by-three, for instance, would give you a total of 18 pages to get lost on. However, some people, such as graphical artists, may welcome a larger workspace.

19.2.5 Using Multiple Desktops

In order to work with multiple desktops, you simply have to configure the Pager to display the number of desktops you want. Each desktop will have the same number of pages, the number you specified using DeskTopSize.

To specify more than one desktop, you'll need to edit a line that looks something like this one:

*FvwmButtons(2x2 Frame 2 Swallow(UseOld) "FvwmPager" "Module FvwmPager 0 0")

This line incorporates the Pager into the FvwmButtons module (the button bar). The two numbers at the end of the definition line (0 0) give the range of desktops visible. The first desktop is number 0, and in this case the last desktop is also number 0 (i.e., there is only one).

If you want two desktops, change the final number to a 1:

*FvwmButtons(1x2 Frame 2 Swallow(UseOld) "FvwmPager" "Module FvwmPager 0 1")

The following line creates a Pager with four desktops, numbered 0 through 3:

*FvwmButtons(1x2 Frame 2 Swallow(UseOld) "FvwmPager" "Module FvwmPager 0 3")

Few people require this much space. But even if you add only a single desktop, you may have to change the overall dimensions of the Pager, and thus of the button bar that contains it, in order to have a reasonably sized view of your various desktops. You may also have to reallocate the space you have so that the Pager gets a large enough area.

There are a few relevant sizes you can tinker with to make room for a Pager that shows multiple desktops:

  • The dimensions of the button bar (FvwmButtons module)

  • The number of columns the button bar is divided into

  • How many of those columns the Pager takes up

A typical FvwmButtons module might be 520 pixels wide and 100 pixels high, starting in the lower right corner of the screen:

*FvwmButtonsGeometry 520x100-1-1

And it might be configured as two rows and five columns (the sizes of which are entirely dependent on FvwmButton's geometry):

*FvwmButtons(Frame 2 Padding 2 2 Container(Rows 2 Columns 5 Frame 1 Padding

10 0))

In this particular setup, the Pager takes up a one-column by two-row section of the FvwmButtons module:

*FvwmButtons(1x2 Frame 2 Swallow(UseOld) "FvwmPager" "Module FvwmPager 0 1")

The Icon Manager takes up three columns:

*FvwmButtons(3x2 Frame 2 Swallow "FvwmIconMan" "Module FvwmIconMan")

And the remaining column is occupied by the desktop applications (e.g., xbiff, xclock, xload) that run within a container in the FvwmButtons module:

*FvwmButtons(1x2 Frame 0 Container(Rows 2 Columns 2 Frame 0))

*FvwmButtons(Frame 2 Swallow(UseOld,NoHints,Respawn) "xbiff" 'Exec exec

xbiff -bg bisque3')

*FvwmButtons(Frame 3 Swallow(UseOld,NoHints,Respawn) "xclock" 'Exec exec

xclock -bg

bisque3 -fg black -hd black -hl black -padding 0 update 1')

*FvwmButtons(2x1 Frame 2 Swallow(UseOld,NoHints,Respawn) "xload" 'Exec exec

xload -bg bisque3 -fg black -update 5 -nolabel')

Notice that the container is subdivided into two rows and two columns. The top row contains xbiff and xclock, and the bottom row contains xload, using both columns.

Back to the issue of multiple desktops. If you want two desktops, set that up by changing the number of the final desktop to a 1 at the end of this line, as we did earlier:

*FvwmButtons(1x2 Frame 2 Swallow(UseOld) "FvwmPager" "Module FvwmPager 0 1")

Then, to make the Pager big enough to display both desktops adequately, add some pixels to the width of the button bar. Here's an extra hundred added to the 520 we started with:

*FvwmButtonsGeometry 620x100-1-1

And let's also reallocate the available five columns so that the Icon Manager takes up only two (rather than the three it started with), and give the extra column to the Pager. The section with the applications remains a single column wide:

*FvwmButtons(2x2 Frame 2 Swallow "FvwmIconMan" "Module FvwmIconMan")

*FvwmButtons(2x2 Frame 2 Swallow(UseOld) "FvwmPager" "Module FvwmPager 0 1")

*FvwmButtons(1x2 Frame 0 Container(Rows 2 Columns 2 Frame 0))

Figure 19-2 shows our new double desktop reflected in the updated button box. This is just one sample customization. With your individual needs and display specifics, you can imagine how complicated this can get. But it's easy to test your changes by simply restarting the window manager.

Figure 19-2. The modified FvwmButtons module shows two desktops in the Pager

19.2.6 Making the Same Window Appear on Every Page

A window that appears on every virtual screen page is called a sticky window because it "sticks" to the screen. Some windows are designated as sticky in the system.fvwm2rc file, among them xbiff, programs ending in lock (e.g., clock programs such as xclock and oclock), and all the fvwm2 modules (because you need the button bar, Pager, etc., on every page).

If you want a window to be sticky, you need to specify that in your .fvwm2rc file. The specification requires you to use the Style variable, followed by the client's name, and the parameter Sticky. The Style variable is used to set many different characteristics. Here are some lines you might see in a configuration file to establish that a window is sticky, among other things:

Style "xbiff"       NoTitle, Sticky, WindowListSkip, ClickToFocus

Style "*lock"       NoTitle, NoHandles, Sticky, WindowListSkip, ClickToFocus

Style "Fvwm*"       NoTitle,  Sticky, WindowListSkip

Notice that the Style variable can recognize a wildcard character (*) to widen the scope of the definition. The value Fvwm* encompasses all fvwm2 modules.

Now try adding the following line, which specifies that an application called xpostit will stick:

Style "xpostit"      Sticky

Practically speaking, you probably also want to specify that xpostit uses click-to-type focus and doesn't appear on the WinList, so this definition is better:

Style "xpostit"     Sticky, WindowListSkip, ClickToFocus

In most cases, you'll want only small windows that you run a single instance of (and that you use frequently) to be sticky. Having a terminal emulator like xterm appear on every page would take up too much space. However, if you do want a client like xterm to follow you around, be sure to give that instance of the program a distinctive name using the -name option.

For example, in your X session startup file you can run an xterm you name mailwindow:

xterm -name mailwindow &

Then, to make that window appear on every page, add the following line to your .fvwm2rc file:

Style "mailwindow"  Sticky

If you want to make a particular window sticky temporarily, look for an Fvwm Window Ops menu under your Root menu. You will commonly find a toggle to (Un)Stick a Window. Or, you can set up such a menu item yourself; see Section 19.4 later in this chapter.

19.2.7 Starting Windows on Different Desktops and Pages

There's an obvious, low-tech way to start applications on different desktops and on different pages within a desktop: switch the view to the desktop and page you want (using the Pager, keyboard shortcuts, or whatever method you like), open a terminal emulator window (e.g., using the Root menu), then run whatever program you want. Voilà—the application window opens on the current desktop and page.

But there are two automated ways to accomplish the same thing. In the first method, you specify in your .fvwm2rc file that certain programs appear on certain desktops and/or pages automatically when you run them. You do this using fvwm2's Style variable, which takes two relevant options: StartsOnPage and StartsOnDesk.[1]

[1] There is also a StartsOnScreen option that specifies which screen to start a window on if you have Xinerama enabled.

StartsOnPage takes up to three numeric arguments. If there is only one argument, it corresponds to the number of the desktop on which to open the application. If there are three arguments, the second and third additionally identify the page using an X,Y coordinate scheme. We'll come back to this in a moment. Two arguments alone are interpreted as the X and Y coordinates of the page.

And what about the closely associated StartsOnDesk variable? StartsOnDesk takes only one argument: the desk number. But since you can set this with StartsOnPage, along with the more specific page address, in practice there is no need to use StartsOnDesk at all. Although it's still supported, StartsOnDesk is an older option that has been replaced by StartsOnPage.

Now back to desktop and page addressing. Let's consider the addressing scheme of a single two-by-two desktop. Just as the first desk is addressed as number 0, the first page on a desk is 0,0. The next page to the right is 1,0. The third page clockwise (the lower-right quadrant) is 1,1. And the fourth page clockwise (the lower-left quadrant) is 0,1.

Supposing there are at least two desktops of four pages each, the following definition says that when you run an xterm called "bigxterm" it is opened on the second desktop (number 1) in the lower-left quadrant (0,1):

Style "bigxterm"     StartsOnPage 1 0 1

Once you make this update to your .fvwm2rc file and restart the window manager, running the command:

xterm -name bigxterm &

opens the window where you want it.

You can accomplish the same thing using X resource syntax on the command line. This strategy may even be a little more practical than putting the definitions in your .fvwm2rc file because you won't have to define many different instances of the various programs (bigxterm, littlexterm, mailwindow, or whatever). The -xrm option (recognized by many X clients) lets you specify an X resource variable on the command line:

xterm -xrm '*Page: 1 0 1' &

You can even put a series of such lines in your X session startup file in order to open applications wherever you want them on your desktop(s) when you log in.

While it looks as if these two methods of opening windows on different desktops/pages (the Style variable with StartsOnPage and the -xrm command-line option) produce identical results, there is actually a subtle difference in behavior. When you use Style with StartsOnPage and you specify only the desktop number, the window is opened on the first page (0,0) of that desk. If you give the same information on the command line (using -xrm), the destination page of the new window is related to the page you're on when you run the command. The new window appears on the analogous page of the desktop you specify.

You have one more alternative if you're interested in opening a window on a different page within the current desktop. Run a window with the -geometry option and supply large enough coordinates to place it on a particular page in the desktop. If you use a desktop three pages square, the following line places a window in the middle page of the nine-page grid:

xterm -geometry +1200+1200 &

Keep in mind, however, that display-specific characteristics play a big part in gauging these distances, and they are not easy to guess.

19.2.8 If It's Too Hard (or Easy) to Move the Pointer Between Pages

If you're navigating the desktop by moving the pointer and you find it either too easy or too difficult to go from one page to the next, there's a configuration file variable you can customize. The aptly named EdgeResistance variable lets you adjust how easy it is to move the pointer beyond the perimeter of the current page.

The variable takes two parameters. The first, which is more relevant to the problem at hand, is the number of milliseconds the pointer must remain at the screen edge before you move onto the next page. The second parameter, which has to do with the way a window is moved between pages, is the number of pixels over the edge of the screen a window's border must move before it moves partially off the screen. Typical default settings are:

EdgeResistance 250 10

Some people find that the EdgeResistance they're working with is too low, with the inconvenient result that they inadvertently knock the pointer off the current screen page. If this is your problem, you can increase the first parameter:

EdgeResistance 500 10

A first parameter between 500 and 1000 greatly enhances the resistance. The maximum resistance is 10000, which actually makes it impossible to page over.

If you have the opposite problem and have to bounce the mouse against what feels like a hard rubber wall in order to page over, try reducing the first number:

EdgeResistance 100 10

In a typical default configuration, fvwm2 is set up with menu options that let you change your paging options on the fly. A number of these options are located in the Root menu, in the Fvwm Simple Config Ops menu. Thus, you can toggle the ability to page on and off with Full Paging On and All Paging Off.

All Paging Off limits you to keeping the pointer on the current page. You might prefer this if you're going to be working on that page for a while and you don't want to worry about knocking the pointer onto another page. You can toggle paging back on with the Full Paging On menu item. There are other items to constrain paging in different ways (e.g., Horizontal Paging Only, Vertical Paging Only). The Partial Paging item lets you move the pointer so that the view straddles two adjacent pages; the area you see will be highlighted in the Pager window.

The item Full Paging & Edge Wrap actually expands the range of paging possibilities. Normally when you reach the edge of a desktop, you can't move the pointer beyond it. With this item selected, you can drag the pointer beyond the edge of the desktop and it wraps around to the page on the other side (either horizontally or vertically). Thus, if you have the pointer in the upper-right page of a two-by-two desktop, and you drag the pointer off the right edge, it wraps around to the upper-left page of that desktop.

Underlying all these menu items is the EdgeScroll variable. Here are the EdgeScroll parameters that map to the various menu items:

Full Paging ON               EdgeScroll 100 100

All Paging OFF               EdgeScroll 0 0

Horizontal Paging Only       EdgeScroll 100 0

Vertical Paging Only         EdgeScroll 0 100

Partial Paging               EdgeScroll 50 50

Full Paging & Edge Wrap      EdgeScroll 100000 100000

EdgeScroll's two parameters specify the percentage of a page to scroll when you reach the border of the page. The first parameter is for horizontal moves, the second for vertical. If the horizontal and vertical percentages are multiplied by 1000, scrolling will wrap around at the edge of the desktop. EdgeScroll 100000 100000 will wrap for both horizontal and vertical moves.

Rather than rely on menu items like these, you can make any of these options the default behavior by putting the EdgeScroll variable on its own line in your .fvwm2rc file. See the fvwm2 manpage and check out the system.fvwm2rc file for guidance.

Note that none of these variations lets you scroll from one desktop to another. The next section shows how to configure some keyboard shortcuts to do just that.


19.3 Adding Keyboard Shortcuts

The system.fvwmrc file that we started with offers little in the way of keyboard shortcuts, or accelerators, for window management functions. But if you're one of those users who prefer to keep their hands on the keyboard and off the mouse as much as possible, you can easily define keys in your .fvwm2rc file to perform a variety of functions.

19.3.1 Navigating the Desktop

The Pager is a great tool for getting around one or more desktops, but many people hate using the mouse. You can configure certain keys and key combinations to let you move around in various ways.

Add the following lines to your .fvwm2rc file to set up key combinations to scroll one page in any direction on the desktop using Ctrl plus an arrow key. The view scrolls in the direction of the arrow.

Each definition uses the Key variable followed by:

  1. The name of the key

  2. The context (location) in which it must be typed

  3. Any modifying keys that must also be held down

  4. The action initiated by the key or key combination

Thus, in the following example, the first definition line says that pressing the left arrow key (Left) in any (A) context, while also holding down the Ctrl (C) key scrolls the screen one page to the left on the current desktop:

# Press arrow + Control in any context
# to scroll by one page in the direction of the arrow
Key Left            A            C            Scroll -100 0
Key Right           A            C            Scroll +100 +0
Key Up              A            C            Scroll +0  -100
Key Down            A            C            Scroll +0  +100

Table 19-1 summarizes the functionality.

Table 19-1. Key combinations to change the page

Key combination

Moves view

Control, right arrow key

One page to the right

Control, left arrow key

One page to the left

Control, up arrow key

One page up

Control, down arrow key

One page down

The Scroll variable takes the same parameters as EdgeScroll, which was explained in the previous section. See the fvwm2 manpage for more information. Note that the key combinations we've defined let you get around a single desktop but won't let you advance to another desktop. We'll deal with that contingency later.

Here's another possible key binding. This one advances the view to every page in the desktop in order, and finally wraps back to the first page. You use the Tab key while holding down Control, again in any context. The definition line looks like:

# Press Tab + Control in any context to scroll
# by one page with wrap scrolling
Key Tab         A       C       Scroll 100000 0

Table 19-2 summarizes another page-changing combination.

Table 19-2. Another key combination to change the page

Key combination

Moves view

Control, Tab

To the next page in the desktop

Since application windows can straddle pages, there may be times when you want the screen to display a screenful other than a page proper. (You might also want to look at windows on two different pages at once.) The following shortcuts scroll the view one-tenth of a page at a time. Instead of Control, these shortcuts use the so-called Meta key. This is a symbolic name—the actual key that serves the Meta function varies from keyboard to keyboard. In many cases, the key labeled Alt serves as the Meta key. Here are the configuration file definition lines:

## Press arrow + meta key in any context
## to scroll by 1/10 of a page in the direction of arrow
Key Left            A            M            Scroll -10 +0
Key Right           A            M            Scroll +10 +0
Key Up              A            M            Scroll +0   -10
Key Down            A            M            Scroll +0   +10

These lines establish the functionality outlined in Table 19-3.

Table 19-3. Key combinations to scroll the page by 1/10

Key combination

Moves view

Meta, left arrow key

One-tenth of a page to the left

Meta, right arrow key

One-tenth of a page to the right

Meta, up arrow key

One-tenth of a page up

Meta, down arrow key

One-tenth of a page down

If you have more than one desktop, you can also create shortcuts to move between desktops. The following two shortcuts let you go back and forth between desktops in a two-desktop environment:

## Press Control + Return in any context
## to scroll forward by 1 desktop
Key Return         A       C       Desk 1 1 1
## Press Shift + Control + Return in any context
## to scroll back by 1 desktop
Key Return         A       SC      Desk -1 0 0

Table 19-4 summarizes these shortcuts.

Table 19-4. Key combinations to scroll to the next desktop

Key combination

Moves view

Control, Return

One desktop ahead

Shift, Control, Return

One desktop back

The second and third parameters to the Desk variable constrain the paging so that you can't page beyond the first or second desktops. (Theoretically, you can page outside the view of the Pager!) If you have more than two desktops, you will need to edit these definitions. See the fvwm2 manpage for more about the Desk variable.

19.3.2 Moving the Pointer

The previous section outlines some keyboard shortcuts you can define to scroll the page view. But you can also define shortcuts to move the position of the pointer on the screen. If you prefer using the keyboard to the mouse, these shortcuts can come in handy. They employ the CursorMove variable, also described on the fvwm2 manpage.

The keyboard accelerators in the first group move the cursor symbol one-tenth of a screen at a time. The first definition line says that pressing the left arrow key in any (A) context, while also holding down the Shift (S) and Meta (M) keys, moves the cursor one-tenth of a page in the direction of the arrow:

## Press Shift + Meta + arrow in any context
## to move the pointer by 1/10 of a page in direction of arrow
Key Left            A            SM            CursorMove -10  +0
Key Right           A            SM            CursorMove +10  +0
Key Up              A            SM            CursorMove +0   -10
Key Down            A            SM            CursorMove +0   +10

Table 19-5 summarizes the commands.

Table 19-5. Key combinations to move the pointer by 1/10 of the page

Key combination

Moves pointer

Meta, Shift, left arrow key

One-tenth of a page to the left

Meta, Shift, right arrow key

One-tenth of a page to the right

Meta, Shift, up arrow key

One-tenth of a page up

Meta, Shift, down arrow key

One-tenth of a page down

If you want as much control moving the pointer with keystrokes as you do moving it by hand, you can specify shortcuts to move it a mere one percent of a page at a time:

## Press Shift + Control + arrow in any context
## to move the pointer by 1% of a page in direction of arrow
Key Left            A            SC            CursorMove -1 0
Key Right           A            SC            CursorMove +1 +0
Key Up              A            SC            CursorMove +0 -1
Key Down            A            SC            CursorMove +0 +1

Table 19-6 summarizes the commands.

Table 19-6. Key combinations to move the pointer by 1 percent of the page

Key combination

Moves pointer

Shift, Control, left arrow key

One percent of a page to the left

Shift, Control, right arrow key

One percent of a page to the right

Shift, Control, up arrow key

One percent of a page up

Shift, Control, down arrow key

One percent of a page down

19.3.3 Menu and Window Manipulation

So far we've limited our keyboard shortcuts to scrolling the view and moving the pointer. But you can create keyboard bindings for any window manager function.

Here are some sample bindings to perform simple window operations and to display a few menus:

# Keyboard accelerators
Key F1          A       M       Iconify
Key F2          A       M       Move
Key F3          A       M       Resize
Key F4          A       M       Popup "RootMenu"
Key F5          A       M       Popup "Misc-Ops"
Key F6          A       M       Popup "Utilities"
Key F7          A       M       Popup "Module-Popup"
Key F10         A       M       Restart fvwm2
Key F12         A       SM      Close

These are just sample bindings; you may want to set up your own keyboard shortcuts to do entirely different things. But these bindings illustrate some of the possibilities, as well as potential problems.

In our sample definition lines, the first binding specifies that if you press the F1 function key while holding down the Meta (M) key, with the pointer in any (A) context, the focus window is iconified (or deiconified). Meta-F2 lets you initiate moving the focus window, while Meta-F3 starts a resize operation.

Note that if you've adopted the keyboard bindings to move the pointer (as described in the previous section), you can perform the move and resize operations entirely with keystrokes. For example, use Meta-F2 to begin a move, drag the window outline by moving the pointer symbol using the appropriate keyboard shortcuts, then press the Return key to complete the operation.

In addition, we've set up function keys to pop up four different menus, the contents of which are predefined in the .fvwm2rc file. Once a menu is popped up, you can use the up and down arrow keys to highlight items on the menu, right and left keys to move down and up through submenus (cascading menus), the Return key to select an item, and Esc to pop down the menu without making a selection.

Because we're doing a lot of tinkering with fvwm2 customization, we have set up Meta-F10 to restart the window manager. This is much faster than bringing up menus.

We've also created a key combination to close the focus window: Shift-Meta-F12. Certainly it's handy to be able to get rid of a window with a keyboard shortcut, but you don't want it to be too easy or you may do it by mistake. Having an extra modifying key (Shift) and using the very last function key (F12) require you to act deliberately in closing a window using this method.


19.4 Customizing Menus

Among the window manager features and functions defined in the configuration file are the contents of menus. The system.fvwm2rc file generally defines a number of menus intended to be useful to a large percentage of people. But the menus you have and what they offer are basically up to you.

Typically the Root menu is defined as follows:

AddToMenu RootMenu      "Root Menu"               Title

+                       "XTerm"                   Exec exec xterm

+                       "Rxvt"                    Exec exec rxvt

+                       ""                        Nop

+                       "Remote Logins"           Popup Remote-Logins

+                       ""                        Nop

+                       "Utilities"               Popup Utilities

+                       ""                        Nop

+                       "Fvwm Modules"            Popup Module-Popup

+                       "Fvwm Window Ops"         Popup Window-Ops

+                       "Fvwm Simple Config Ops"  Popup Misc-Ops

+                       ""                        Nop

+                       "Refresh Screen"          Refresh

+                       "Recapture Screen"        Recapture

+                       ""                        Nop

+                       "Exit Fvwm"               Popup Quit-Verify

You use the AddToMenu variable to create a menu. The first parameter that AddToMenu takes is the name of the menu, in this case RootMenu. The menu name is used to reference the menu elsewhere in the configuration file (e.g., to specify a key binding to pop up the menu). Note that the AddToMenu variable and the menu name are automatically repeated on each line of the menu definition, as indicated by the plus sign.

Each line of the definition creates a line on the menu as seen by the user; types of lines include the menu title, a menu item proper, a blank line, and a separator. The third component of each line specifies the text that appears on that line. The fourth component specifies the window manager function to be performed.

The first line of our example specifies the menu title. Lines with empty text fields ("") together with the Nop ("No operation") function create divider lines on the menu.

The Popup function is worth looking at more closely. Popup specifies that a menu is displayed; the menu name is given as an argument to Popup. When Popup is invoked from another menu, it creates a submenu (or cascading menu). This sample Root menu definition has six submenus, named Remote-Logins, Utilities, Module-Popup, Window-Ops, Misc-Ops, and Quit-Verify. These menus would also be defined using the AddToMenu command elsewhere in the configuration file.

You can start from the default menus in the system.fvwm2rc file and use the fvwm2 manpage to modify the existing menus or create your own. It is simple to replace definition lines in the template menus, and not much more difficult to write a new entry or even a menu from scratch.

You can also change how the menus are displayed. Perhaps you don't want a bunch of cascading menus off the Root menu. In the previous section we set up some function keys to display certain menus. That's one option. You might instead specify pointer buttons to display various menus. In a typical default, the first pointer button displays the Root menu and the second displays the Window Ops menu. But since most Window Ops functions (e.g., Move, Resize, Iconify) are available using the pointer directly on parts of a window, you may instead choose to have the second pointer button display another menu (e.g., Utilities).


19.5 The WinList: Switching the Focus

FvwmWinList is an fvwm2 module that lets you keep track of all the application windows on your many screen pages. Generally the WinList is configured to let you switch the focus to whatever window you want, but you can set it up to perform other operations.

In a typical environment, you can start the WinList from the Fvwm Modules menu on the Root menu. If you prefer to configure fvwm2 to start the WinList automatically, see Section 19.5.2. (You might also configure a keyboard shortcut to start the WinList module; see Section 19.3 for details.)

Some of WinList's appearance and behavior can be customized. We'll see some example module definition lines later. If you are using that example configuration, WinList performs the following operations:

First mouse button click

Switch the focus to the window in question. If the window is iconified, de-iconify. Switch the screen view so that the page with the window is displayed.

Second mouse button click

Iconify/deiconify window; the page displayed does not change.

Third mouse button click

Display a pop-up box containing information about the window in question (e.g., dimensions in pixels, whether it is sticky, permanent, or transient, etc.). Pop down the box by clicking any mouse button on it.

One of the interesting features of the WinList is that none of these commands moves the pointer to the focus window. Instead, the pointer stays on the entry in the WinList that corresponds to the focus window.

In theory, you could simply keep the pointer on the WinList and do all your navigation from there—except when you want to work with the FvwmButtons module or another of the windows that don't normally appear in the WinList.

19.5.1 Distinguishing Multiple Instances of Windows in WinList

The primary limitation of the WinList is that it can be difficult to tell which window in the list is which. Each entry in the WinList gives the text that appears in the corresponding window's titlebar. (If the titlebar is suppressed, it gives the text that would normally appear.) If you tend to run the same program many times simultaneously—e.g., multiple xterms—they all look alike in the WinList. (The one difference is that iconified windows have entries surrounded by parentheses.)

If you get attached to using the WinList, you should probably specify different titles for multiple instances of the same window. The standard X options -title or -name will do the trick. Note, however, that while -title changes only the text in the titlebar, -name literally changes the name of the application. Thus it affects how resources and configuration file parameters are assigned.

19.5.2 Making the WinList Part of Your Default Environment

If you want to make the WinList part of your default environment, edit your configuration file to have the FvwmWinList module run at both initialization and restart of the window manager. In the following example, we've added the third and sixth lines for these purposes:

AddToFunc InitFunction    "I" Module FvwmButtons

+           "I" exec xsetroot -mod 2 2 -fg \#554055 -bg \#705070

+           "I" Module FvwmWinList

AddToFunc RestartFunction "I" Module FvwmButtons

+           "I" exec xsetroot -mod 2 2 -fg \#554055 -bg \#705070

+           "I" Module FvwmWinList

These lines specify that the FvwmWinList module is run whenever you start or restart the window manager. The WinList window appears in the bottom left corner of the screen.

As an alternative, you might make the WinList appear as a pop-up menu. The following definition binds the module to the third pointer button when it is held down on the root window (this may not be as handy as having the module present all the time):

Mouse 3         R       A       Module FvwmWinList Transient

But running a module is different from specifying how it looks and behaves. Like a number of other modules (FvwmButtonBox, FvwmPager, etc.), the various characteristics of the FvwmWinList module are defined elsewhere in the configuration file. Here are some typical definition lines:

#########################FvwmWinList#########################

*FvwmWinListBack #908090

*FvwmWinListFore Black

*FvwmWinListFont -adobe-helvetica-bold-r-*-*-10-*-*-*-*-*-*-*

*FvwmWinListAction Click1 Iconify -1,Focus

*FvwmWinListAction Click2 Iconify

*FvwmWinListAction Click3 Module "FvwmIdent" FvwmIdent

*FvwmWinListUseSkipList

*FvwmWinListGeometry +0-1

The first three lines specify the background color, foreground color, and text font used for the application. The next three define the actions that first, second, and third mouse button clicks invoke when they occur within the WinList. UseSkipList tells the WinList not to list any windows that are assigned the Style classification WindowListSkip elsewhere in the configuration file. (Generally all module windows are classified thus and do not appear in the WinList.) The final line specifies the location at which the window should appear (bottom left corner).

The WinList is also a sticky window; it appears on every page on every desktop. But the configuration file can be confusing. This characteristic is specified elsewhere in the file, using the Style option:

Style "Fvwm*"       NoTitle, Sticky, WindowListSkip

This line specifies that all modules (including the WinList) have no titlebars, are sticky, and do not appear on the WinList. In the case of the FvwmWinList module, having it appear as an entry on itself would be more than a little confusing.


index

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

Team LiB Previous Section


index_SYMBOL

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

& (ampersand)
ex 2nd
logical AND
< > (angle brackets) ex
* (asterisk) 2nd
multiplication operator
@ (at)
ex
tcsh
\ (backslash)
! (bang)
ex
shell invocation, ftp
!~ (bang tilde), gawk
{ } (braces), sed command
[ ] (brackets) 2nd
^ (caret), gawk
: (colon)
ex editor
pattern search, expr
sed
:set command (ex)
tcsh null command
$ (dollar)
execute macro command, ftp
gawk
prompt
sed
. (dot)
?? (double question marks)
" " (double quotes)
= (equals)
ex
sed
\( \) (escaped parentheses)
/ (forward slash)
division operator
sed command
#! (hash bang)
tcsh shell
# (hash mark) 2nd
in shell scripts
sed
tcsh shell
- (hyphen) and metamail command
- (minus operator)
% (modulo operator)
: (null command)
( ) (parentheses)
% (percent)
bash job ID argument
prompt
| (pipe) 2nd
as logical OR symbol
+ (plus) operator
fvwm2
? (question mark) 2nd
ftp help command)
> (redirection operator)
>> (redirection operator)
< (redirection operator)
<< (redirection operator)
; (semicolon)
' ' (single quotes)
~ (tilde)
bash
ex
gawk
sed
tcsh
` (backquote)

Team LiB Previous Section


index_A

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

a command (sed)
abbrev command (ex)
account command (ftp)
aclocal command
ACPI (Advanced Configuration and Power Interface)
Ada programming language, compiling
add command (CVS)
addr2line command
address command (ex)
Address Resolution Protocol [See ARP]
addresses (sed)
addsuffix variable (tcsh)
AddToMenu variable (fvwm2)
admin command (CVS) 2nd
Advanced Package Tool (APT)
Advanced Power Management [See APM]
AFSUSER environment variable (tcsh)
afsuser variable (tcsh)
agetty command
alias command
bash
tcsh
alloc command (tcsh)
Alt-F1 through F12
Alt-F7
Alt-key (Emacs)
ampersand (&)
ex command 2nd
logical AND
ampm variable (tcsh)
and command (gawk)
angle brackets (< >) command (ex)
annotate command (CVS)
ANSI/VT100 terminal emulation, enabling (screen)
Apache, user authentication files, updating (htdigest)
APM (Advanced Power Management)
BIOS driver
BIOS information, displaying (GRUB)
KDE
apmd command
append command
ex
ftp
applets
apropos command
APT (Advanced Package Tool)
apt command
apt-cdrom command (Debian)
apt-config command (Debian)
apt-extracttemplates command (Debian)
apt-ftparchive command (Debian)
apt-get command (Debian) 2nd
apt-sortpkgs command (Debian)
ar command
arbitrary-precision arithmetic, performing with bc
arch command
archives
copying
creating (shar)
creating and restoring (tar)
in CVS
maintenance (ar)
args command (ex)
argv variable (tcsh)
arithmetic operators (expr)
ARP (Address Resolution Protocol) 2nd 3rd 4th [See also RARP]
ifconfig and
arp command
as command
ascii command (ftp)
asort command (gawk)
ASs (autonomous systems)
assembly language, generation of object files
asterisk (*) 2nd
multiplication operator
at (@) command
ex
tcsh
at command
atan2 command (gawk)
atd command
atq command
atrm command
audio media commands
audiosend command
Author keyword (RCS)
autoconf command 2nd [See also autoheader command]
aclocal command and
autocorrect variable (tcsh)
autoexpand variable (tcsh)
autoheader command
autolist variable (tcsh)
autologout variable (tcsh)
automake command
autonomous systems (ASs)
autoreconf command
autoscan command
autoupdate command
awk scripting language [See gawk scripting language]
Team LiB Previous Section


index_B

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

b command (sed)
background module (KDE)
backslash (\)
backslash_quote variable (tcsh)
backspace key
Emacs
badblocks command
bang (!)
ex
shell invocation, ftp
bang tilde (!~), gawk
banner command
basename command
bash shell 2nd 3rd
arithmetic expressions and operators
built-in commands
built-in shell variables
command history
command substitution
fc command
line-edit mode
command-line editing
Emacs mode
vi mode
commands, usage
configuration files
features
filename metacharacters
invocation, options and arguments
job control
pattern matching
prompt
prompt variables
quoting
redirection, usage
special files
syntax
tcsh, compared to
variables
variable substitution
vi mode editing
batch command [See also at command]2nd
bc program
function keywords
identifiers
input-output keywords
math library functions
operators and symbols
statement keywords
bdelete command (ex)
bell command (ftp)
bg command
bash
tcsh 2nd
biff command
binary command (ftp)
binary files, encoding in ASCII (uuencode)
BIND (Berkeley Internet Name Domain)
bind command (bash built-in)
binding (ypbind)
bindkey command (tcsh)
biod daemon
BIOS information, displaying (displayapm)
bison command
blocklist command (GRUB)
blocklists (GRUB)
Boleyn, Erich
Bonobo library
boot command (GRUB)
boot loaders
chainloaders
GRUB [See GRUB]
LILO [See LILO]
Loadlin
boot methods
boot process
boot sector
boot-time kernel options
/boot/grub.conf [See GRUB, conguration file]
bootable CDs, difficulties of making
bootp command (GRUB)
bootpd command
bootpgw command
bootptest command
Bourne shell
braces { }, sed command
brackets [ ] 2nd
branching (CVS)
break command
bash built-in
gawk
tcsh
breaksw command (tcsh)
broadcast messaging (wall)
browsers [See web browsers]
buffer command (ex)
buffers
buffers command (ex)
built-in shell commands
built-ins command (tcsh)
builtin command (bash)
bunzip2 command [See bzip2 command]
bye command
ftp
tcsh
bzcat command [See bzip2 command]
bzcmp command
bzdiff command
bzgrep command [See also grep command]2nd
bzip2 command
bzip2recover command [See bzip2 command]
bzless command [See also less program]2nd
bzmore command [See also more program]2nd

Team LiB Previous Section


index_C

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

c++ command [See g++]
c++filt command
C++ programming language
c++filt command and function overloading
compiling (gcc)
debugging (gdb)
c command (sed)
C programming language
compiling (gcc)
debugging (gdb)
imake command
m4 command
preprocessor command (cpp)
C shell command interpreter (csh)
C-s command (Emacs)
cal command
Caldera package manager [See RPM]
cardctl command
cardmgr command
caret (^), gawk
case command
bash
ftp
tcsh
cat command
GRUB
catalog variable (tcsh)
cc command [See gcc]
cd command
bash built-in
ex
ftp
tcsh
CD-ROMs
bootable, difficulties of making
ejecting
volume names, displaying (volname)
CDDA (Compact Disc Digital Audio), WAV format, converting to
cdda2wav command
cdparanoia command
cdpath variable (tcsh)
cdrdao command
cdrecord command
cdup command (ftp)
center command (ex)
cfdisk command
chage command
chainloader command (GRUB) 2nd
chainloaders
chains
change command (ex)
character encoding conversions (iconv)
chat command
chdir command (tcsh)
checkout command (CVS)
checkpc command
chfn command
chgrp command
chmod command
ftp
chown command
chpasswd
chroot command
chsh command
chvt command
ci command (RCS)
CIDR (Classless Inter-Domain Routing)
cksum command
Classless Inter-Domain Routing (CIDR)
clear command
clock commands
clock, setting (hwclock)
close command
ex
ftp
gawk
cmp command
GRUB
co command (RCS)
col command
colcrt command
colon (:)
:set command
ex editor
pattern search, expr
sed
tcsh null command
color command (GRUB)
color variable (tcsh)
colorcat variable (tcsh)
column command
COLUMNS environment variable (tcsh)
comm command
command command (bash)
command substitution
bash 2nd
gawk
tcsh 2nd
command variable (tcsh)
command-line editing
bash
tcsh
commands
beginnerÕs guide
audio media commands
file management commands
file storage commands
miscellaneous commands
printing commands
program maintenance commands
searching commands
Debian Package Manager
executing as superuser (sudo)
executing with arguments from standard input (xargs)
finding binary, source, and manpages for (whereis)
Linux
options to
listing pathnames of executed files for (which)
running repeatedly (watch)
commit command (CVS)
comp.os.linux newsgroups
comparison commands
bzcmp
bzdiff
cmp
compgen command (bash)
compilers [See also gcc]
Ada
bc [See bc program]
link editor command (ld)
compl command (gawk)
complete command
bash
tcsh
complete=enhance variable (tcsh)
compress command
concatenation command [See cat command]
Concurrent Versions System [See CVS]
configfile command (GRUB)
configuration files
bash
bootpd
fvwm2
GRUB
inetd.conf
LILO
rpm command
tcsh
vi 2nd
configuration scripts, generating
context menus
continue command
bash
gawk
tcsh
continue variable (tcsh)
continue_args variable (tcsh)
copy command (ex)
copying files
copyleft
CORBA (Common Object Request Broker Architecture)
corner panels (GNOME)
correct variable (tcsh)
cos command (gawk)
country-specific settings, displaying
cp command
cpio command
cpp command [See also gcc]2nd
cr command (ftp)
CRCs (cyclic redundancy checks), performing
cron command
crontab command
crontab files
csh command [See also tcsh command]2nd
csplit command
ctags command
ctime format
Ctrl-Alt-F1 through F12
Ctrl-key (Emacs)
commands
Ctrl-Z command
bash
tcsh
CUPS (Common Unix Print System)
cut command
CVS (Concurrent Versions System) 2nd
access methods
admin command 2nd
security risks
administrator reference
CVSROOT environment variable
branching
checkoutlist file
client global options
commands
for administrators
format of
for users
commitinfo file
common client options
config file
configuring
conflicts and merging
cvsignore file
CVSROOT directory
administrative file variables
files
cvswrappers file
environment variables
global options
global server option
gotchas
history file
importing from RCS
importing into CVS 2nd
code snapshots
from PVCS
from SCCS
locking model
loginfo file
merging model
modules file
notify file
passwd file
password setup
rcsinfo file
readers file
repositories
creating
making changes
structure
repository locators
sandboxes
creating
CVS directory files
.cvsignore files
.cvswrappers files
sharing
structure
security
tagging
taginfo file
user reference
users file
verifymsg file
writers file
cvs command
cwd variable (tcsh)
cyclic redundancy checks (CRCs), performing

Team LiB Previous Section


index_D

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

d command (sed)
D command (sed)
daemon commands
daemons
NFS daemons
routing daemons
xinetd
DAO (disk-at-once) mode
date command
format
Date keyword (RCS)
dbm files
creating (makedbm)
dd command
deallocvt command
Debian Package Manager 2nd
commands
files 2nd
package flags
package priorities
package/selection states
shell and Perl scripts
debug command
ftp
GRUB
debugfs command
debugging tools
addr2line
gdb command
gprof
patch command
strace command
declare command (bash)
default command (tcsh)
del key
delete command
ex
ftp
gawk
dependencies
dependency files, creating
depmod command
.desktop files (KDE)
devdump command
device command (GRUB)
device images, displaying
devices
hard disks as
swapping, paging
disabling for (swapoff)
enabling for (swapon)
dextract variable (tcsh)
df command
dhcp command (GRUB)
diff command
CVS
diff3 command
dig command
dip command
dir command [See also ls command]2nd
ftp
dircolors command
directories
creating (mdir)
displaying verbosely (vdir)
listing contents of
dir
ls
dirname command [See also basename command]2nd
dirs command
bash
tcsh
dirsfile variable (tcsh)
dirstack variable (tcsh)
disconnect command (ftp)
disk buffers, flushing to disk (update)
disk space, measuring
disk usage, displaying
du
MS-DOS
disk-at-once (DAO) mode
disks
ext2 filesystem, formatting for
MS-DOS formatting
mformat
mkdosfs
disown command (bash)
DISPLAY environment variable (tcsh)
displayapm command (GRUB)
displaymem command (GRUB)
distributions
dmesg command
DNS (Domain Name Service)
servers, querying
dnsdomainname command [See also hostname command]2nd
dnssec-keygen command
dnssec-makekeyset command
dnssec-signkey command
dnssec-signzone command
do command (gawk)
document formatting commands
groff
gs
documentation, accessing
info command
man command
manpath command
whatis command
dollar ($)
execut macro command, ftp
gawk
prompt
sed command
Domain Name Service (DNS)
domain names
researching (whois)
domainname command 2nd
domains
dosfsck command 2nd [See also fsck command]
dot (.)
double quotes (\\x22)
dpkg command (Debian) 2nd
dpkg-deb command (Debian) 2nd
dpkg-query command (Debian)
dpkg-split command (Debian)
drawer (GNOME)
dselect command (Debian) 2nd
dspmbyte variable (tcsh)
du command
dual booting
Linux and Windows NT/2000/XP
dump command (GRUB)
dumpe2fs command
dumpkeys command
dunique variable (tcsh)

Team LiB Previous Section


index_E

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

e2fsck command 2nd [See also fsck command]
e2image command
e2label command
echo command
bash
tcsh
echo variable (tcsh)
echo_style variable (tcsh)
echotc command (tcsh)
ed editor
edge panels (GNOME)
EdgeResistance variable (fvwm2)
edit command
CVS
ex
edit variable (tcsh)
EDITOR environment variable
bash 2nd
tcsh
editors command (CVS)
egrep command [See also grep command]2nd
eject command
ellipsis variable (tcsh)
else command (tcsh)
elvis text editor
elvtune command
Emacs editor
bindings, compared to vi bindings
buffers
command-line editing mode
bash
tcsh
commands
buffer manipulation
capitalization
centering
Ctrl-key commands
cursor movement
deletion
essential commands
file handling
help 2nd
indentation
macros
marking
Meta-key commands
paragraphs and regions
searching
special shell mode characters
stopping and undoing
summary by name
transposition
windows
word abbreviation
common problems
cutting and pasting in
Del or Backspace, fixing in
editing modes
kill and yank
point and mark
windows
embed command (GRUB)
enable command (bash)
encryption
keys, generating (ssh-keygen)
using SSH
end command (tcsh) 2nd [See also foreach command]3rd [See also while command]
end-of-file character (EOF)
endif command (tcsh)
endsw command (tcsh)
env command
environment variables
CVS
tcsh
EOF (end-of-file) character
equals (=)
ex
sed
etags command [See also Emacs text editor]2nd
/etc/at.allow
/etc/at.deny
/etc/exports file
/etc/fstab file
/etc/hosts.deny file
/etc/hosts.allow file
/etc/inetd.conf
/etc/lilo.conf [See LILO, configuration file]
/etc/rpmrc file
eval command
bash
tcsh
ex editor 2nd 3rd
command syntax
command-line options
commands
alphabetical summary
vi, entering from
:set command
exec command
bash
tcsh
exit command
bash
gawk
tcsh
exp command (gawk)
expand command
export command
bash
CVS
expr command
expressions, testing (test)
ext access method (CVS)
ext2 (Second Extended Filesystem)
debugging
disk formatting
e2fsck command
ext3, converting to
tuning (tune2fs)
ext3 (Third Extended Filesystem)
journaling level, specifying
potential booting issues
Extensible Filesystem (XFS)
eXternal Data Representation (XDR)
exusage command (ex)

Team LiB Previous Section


index_F

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

false command
Fast Lexical Analyzer Generator (flex) command
fc command (bash)
fdformat command
fdisk command [See also cfdisk command]2nd
fetchmail command
fflush command (gawk)
fg command
bash
tcsh
fg job control command (tcsh)
fgconsole command
fgrep command
fignore variable (tcsh)
file archives, copying
file command
ex
file compression
gzexe command
gzip command
file management commands
chgrp
chmod
chown
compress
cp
cpio
csplit
file storage commands
file transfer commands
lftp
lftpget
filename expansion vs. pattern matching
files
access modes, changing (chmod)
archives, copying from or restoring to (tar)
attributes, listing
byte, word, and line counts, displaying (wc)
character encoding conversions (iconv)
checksums, calculating for (sum)
classification of (file command)
columnar output, formatting in
comparison
cmp command
comm command
compressed to uncompressed files (zcmp)
diff command
diff3 command
sdiff
zdiff command
copying
between Unix and MS-DOS partitions
creating or updating (touch)
crontab files
Debian package management
disabling for swapping, paging (swapoff)
display format options (hexdump)
duplicate lines, removing (uniq)
enabling for swapping, paging (swapon)
fgrep, searching with
finding binary, source, and manpages for (whereis)
first lines, displaying (head)
last lines, displaying (tail)
linking 2nd
listing (ls)
locking (lockfile)
merging (merge)
object files, displaying profile data for
overwriting to make unrecoverable
ownership, changing (chown)
printing (lpr) [See also CUPS; LPRng line printer daemon]2nd
in reverse (tac)
reading compressed files to output (zcat)
renaming zipped files (zforce)
secure copying between networks (scp)
sorting (sort)
splitting
csplit
split
string matches, searching for (look)
text files, manipulating
cut command
text, opening in vi
transfer between networks [See ftp]
uncompressing
and paging (zless)
and passing to grep (zgrep)
from .Z and recompressing to .gz format (znew)
uncompress command
filesystems
exporting
images, displaying
journaling
managing
mounting
potential booting issues
types
unmounting (umount)
filetest command (tcsh)
find command
GRUB
fingerd command
firewalls
compiling support
FTP transfers (KDE)
ipchains command
iptables command
proxy servers and (KDE)
setting rules for in ipchains
in iptables
flags, Debian Package Manager
flex (Fast Lexical Analyzer Generator) command 2nd [See also lex command; bison command; yacc command]
floating panels (GNOME)
floppy disks
configuring (setfdprm)
formatting (fdformat)
fmt command
fold command
ex
foldclose command (ex)
foldopen command (ex)
for command
bash
gawk
foreach command (tcsh)
fork access method (CVS)
form command (ftp)
formail command
formatting disks
floppies (fdformat)
MS-DOS (mformat)
Fortran programming language, compiling (gcc)
forward slash (/)
division operator
sed command
free command
free disk space, measuring
free software
Free Software Foundation (FSF)
freenode IRC network, Linux channels
freenode IRC service
fsck command
fsck.ext2 command [See e2fsck command]
fsck.minix command
fsck.msdos [See dosfsck command]
FSF (Free Software Foundation)
fstest command (GRUB)
ftp (File Transfer Protocol)
commands
secure transfer using ssh (sftp)
tftp command
ftpd command
ftpd daemon
function command
bash
gawk
fvwm2 window manager
AddToMenu variable
application window management
button bar
cascading menus
configuration changes, implementing
configuration files
customizability
desktop configuration
EdgeResistance variable
features
focus configurations
fvwm2 web site
FvwmPager (fvwm2)
FvwmWinList 2nd
mouse operations
GNOME support
Icon Manager
keyboard shortcuts
menu and window manipulation
for navigation
for pointer movement
manpages
menus, customizing
modules
Pager
paging options
pointer navigation
Popup function
switching from GNOME or KDE
window configuration
StartsOn options
sticky windows
window management
.fvwm2rc file
FvwmWinList (fvwm2)
fwhois command [See whois command]
Team LiB Previous Section


index_G

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

g command (sed)
G command (sed)
g++ command [See also gcc]2nd
gated routing daemon
gateways
protocols
gawk editor 2nd
gawk scripting language
array assignments
bang tilde (!~)
BEGIN pattern
boolean operators
caret (^)
command-line syntax
commands
alphabetical summary
listing by group
dollar ($)
END pattern
operators
options
patterns
procedures
PROCINFO array
system variables
tilde (~)
variables
variable assignments
gcc (GNU Compiler Collection)
general options
options
linker
warning
pragma directives
GDB (GNU DeBugger)
gensub command (gawk)
geometry command (GRUB)
get command (ftp)
getkeycodes command
getline command (gawk)
getopts command (bash)
getty [See agetty command]
GhostScript, gs command
gid variable (tcsh)
glob command (ftp)
glob command (tcsh)
global command (ex)
GNOME desktop 2nd
adding icons
Control Center
accessibility tool
background tool
bounce keys
date and time tool
file associations tool (MIME types)
fonts tool
hardware settings
keyboard shortcuts tool
keyboard tool
look and feel settings
manage software tool
menus button
mouse settings tool
network proxies
password, changing
peripherals
repeat keys
screensavers tool
session management tool
slow keys
sound tool
sticky keys
system settings tools
theme selection
toggle keys
URL handlers tool
GConf (configuration database)
.gnome-desktop directory
launcher
menu panel
menus and panel menus
mouse
arrow keys, using for
middle button features
panels 2nd
applets
application launchers, adding
creating
options
panel types
personal settings
start menu
V. 2 platform
V. 2.0 platform
compared to V. 1.4
GNU C language preprocessor command (cpp)
GNU Network Object Model Environment
GNU Zebra routing daemon
GNU/Linux
goto command (tcsh)
GPL (General Public License)
gpm command
gprof command
graphical desktops
developer web sites
differences
fvwm2 [See fvwm2 window manager]
GNOME [See GNOME desktop]
KDE [See KDE desktop]
licensing
startup files
grep command
bzgrep
egrep and
groff command
groffer command
GROUP environment variable (tcsh)
group variable (tcsh)
groupadd command
groupdel command
groupmod command
groups command
grpck command
grpconv command
grpunconv command
GRUB (Grand Unified Bootloader)
blocklists
boot-time kernel options
commands
blocklist
boot
bootp
cat
chainloader
cmp
color
configfile
debug
device
dhcp
displayapm
displaymem
dump
embed
find
fstest
ftpserver
geometry
halt
help
hide
ifconfig
impsprobe
initrd
install
ioprobe
kernel
lock
makeactive
map
md5crypt
module
modulenounzip
pager
partnew
parttype
password
pause
quit
rarp
read
reboot
root
rootnoverify
savedefault
serial
setkey
setup
splashimage
terminal
testload
testvbe
unhide
uppermem
vbeprobe
configuration file
device map
grub command syntax
GRUB shell
initrd option
installing
LILO, compared to
menu interface
naming conventions
stages
gs command
gserver access method (CVS)
gsub command (gawk)
gunzip command [See gzip command]
gzexe command
gzip command

Team LiB Previous Section


index_H

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

h command (sed)
H command (sed)
halt command
GRUB
hard disks
devices, designation as
naming conventions
under GRUB
parameters, setting (hdparm)
partitioning
cfdisk command
fdisk command
hash bang (#!)
tcsh shell
hash command
bash
ftp
hash mark (#) 2nd
in shell scripts
sed
tcsh shell
hashstat command (tcsh)
hdparm command
head command
Header keyword (RCS)
help
Emacs, invoking in 2nd
help command
bash
CVS
ex
ftp
GRUB
hexdump command
hide command
ex
GRUB
histchars variable (tcsh)
histdup variable (tcsh)
histfile variable (tcsh)
histlit variable (tcsh)
history command
bash
CVS
tcsh
history variable (tcsh)
HOME environment variable (tcsh)
home variable (tcsh)
host command
HOST environment variable (tcsh)
hostid command
hostname command
HOSTTYPE environment variable (tcsh)
HPATH environment variable (tcsh)
htdigest command
hup command (tcsh)
hwclock command
hyphen (-) and metamail command

Team LiB Previous Section


index_I

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

i command (sed)
ICMP (Internet Control Message Protocol)
iconv command
id command
Id keyword (RCS)
IDE drives, designation as devices
ident command (RCS)
identd command
idle command (ftp)
if command
bash
gawk
tcsh
ifconfig command 2nd
GRUB
ignoreeof variable (tcsh)
image command (ftp)
image section options
imake command [See also cpp command; make command]2nd
IMAP (Interactive Mail Access Protocol) server daemon
imapd command
implicitcd variable (tcsh)
import command (CVS)
impsprobe command (GRUB)
in.fingerd command
in.ftpd command
in.identd command
in.rlogind command
in.tftpd command [See tftpd command]
index command (gawk)
index keyword (expr)
inetd command
info command
init command
CVS
processes invoked by (agetty)
initrd
initrd command
GRUB
inode contents, displaying (stat)
inputmode variable (tcsh)
insert command (ex)
insmod command
install command
GRUB
installation commands
int command (gawk)
Interactive Mail Access Protocol (IMAP) server daemon
Internet Boot Protocol Gateway
Internet Boot Protocol server
Internet connections, initiating
chat command
dip command
Internet Control Message Protocol (ICMP)
Internet protocols
Internet relay chat (IRC)
internet services daemon
ioprobe command (GRUB)
IP addresses
ipchains
2.2 kernel, compiling support into
ipchains command
ipchains-restore command
ipchains-save command
ipcrm command
ipcs command
iptables
iptables command 2nd
iptables-restore command
iptables-save command
IPv6
IRC (Internet relay chat)
ISO9660 images
contents, displaying
information, displaying
integrity, verifying
size, displaying
isodump command
isoinfo command
isosize command
isovfy command
ispell command

Team LiB Previous Section


index_J

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

Java programming language, compiling (gcc)
JFS (Journaled Filesystem)
job control
bash
tcsh
jobs command
bash
tcsh
join command
ex
journaling filesystems [See also ext3]2nd
jumps command (ex)

Team LiB Previous Section


index_K

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

k command (ex)
kbd_mode command
kbdrate command
KDE desktop 2nd
accessibility options
application launch feedback, setting
application windows
color selection
control bar
Control Center
context-sensitive help
cryptography
CUPS
default environment, setting as
desktop
adding links
background
desktop folder
preferences
email configuration
file management
fonts
icon configuration
keyboard configuration
accessibility options
kwin window manager
laptop power and battery management
look and feel
MIME file types
modules
mouse configuration
accessibility options
MS Windows share configuration
nationality and language configuration
network configuration
OpenSSL
panel
adding links
configuration
passwords 2nd
personalization options
screensaver
session management
shortcuts
SOCKS support
sound configuration
spell checkers
status information
style settings
system component information, accessing
system configuration modules
date and time
fonts
login manager (kdm)
printing manager (KDEPrint)
web browsing
taskbar
taskbar configuration
terminal emulator 2nd
theme manager
web browsers 2nd
window behavior configuration
window decoration preferences
kernel command (GRUB)
kernel image
kernels
boot-time options
compiling firewall support into
examining or modifying (sysctl)
managing
scancode-to-keycode mapping table, viewing
video configuration (vidmode)
kernelversion command
keyboards
character repeat rate, setting
driver translation tables, listing
modes, setting
putting in Unicode mode
keycodes, displaying (showkey)
keymaps, loading
keywords (expr)
kill command
bash
Emacs
tcsh 2nd
killall command
killall5 command
killdup variable (tcsh)
killring variable (tcsh)
klogd command
Konqueror file manager and browser (KDE) 2nd
Konsole terminal emulator (KDE) 2nd
Korn shell
kserver access method (CVS)
kserver command (CVS)
ksyms command
kwin (KDE)

Team LiB Previous Section


index_L

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

l command (sed)
LANG environment variable (tcsh)
last command
lastb command
lastlog command
LC_CTYPE environment variable (tcsh)
lcd command (ftp)
ld command
ldconfig command
ldd command
left command (ex)
length command (gawk)
length keyword (expr)
less program
bzless
commands
keybindings, configuring for (lesskey)
options
lesskey command
let command (bash)
lex [See flex]
lftp command
lftpget command
LILO (Linux Loader)
boot-time kernel options
configuration file
global options
image options
kernel options
GRUB, compared to
initrd option
lilo command 2nd
limit command (tcsh)
LINES environment variable (tcsh)
link command
link editor (ld)
linker options, gcc
Linux 2nd
advantages of
default shell [See bash shell]2nd
changing
distributions and support
online support
periodicals
shells [See shells]
Unix, compared to
Usenet newsgroups
web sites devoted to
Linux documentation
Linux User Groups (LUGs)
list command (ex)
listflags variable (tcsh)
listing loaded modules (lsmod)
listjobs variable (tcsh)
listlinks variable (tcsh)
listmax variable (tcsh)
listmaxrows variable (tcsh)
ln command
loadkeys command
Loadlin
initrd option
local access method (CVS)
local command (bash)
locale command
locate command
lock command (GRUB)
Locker keyword (RCS)
lockfile command
locking model
CVS
log command
CVS
gawk
tcsh
Log keyword (RCS)
logger command
logical operators (expr)
login command 2nd
CVS
tcsh
login shells, changing (chsh)
logins
display of
bad login attempts (lastb)
last
lastlog
finding usersÕ login names
KDE, management in
loginsh variable (tcsh)
logname command
LOGNAME environment variable (tcsh)
logout command
bash
CVS
tcsh
logout variable (tcsh)
logrotate command
look command
loop devices, setting up (losetup)
losetup command
lpc command
lpd command
lpd daemon
lpq command
lpr command
lprm command
LPRng line printer daemon
printer capability database, inspection and repair
lpstat command
ls command [See also dircolors command]2nd
ftp
ls-F command (tcsh)
LS_COLORS environment variable
LS_COLORS environment variable (tcsh)
lsattr command
lshift command (gawk)
lsmod command
LUGs (Linux User Groups)

Team LiB Previous Section


index_M

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

m4 command
macdef command (ftp)
machine architecture, identifying
machine uptime status, tracking (ruptime)
MACHTYPE environment variable (tcsh)
mail commands
audiosend
biff
fetchmail
formail
imapd
mail
mailq
mailstats
mailto
metamail
sendmail
MAIL environment variable (tcsh)
mail filtering, formail command
mail variable (tcsh)
mailq command
mailstats command
mailto command
make command
description file lines
functions
internal macros
macro modifiers
macro string substitution
pattern rules
special target names
makeactive command (GRUB)
makedbm command 2nd
makemap command
man command
manpages
groffer, displaying with
manpath command
map command
ex
GRUB
maps (NIS)
mark command (ex)
marks (Emacs)
marks command (ex)
masquerading
master boot record [See MBR]
match command (gawk)
match keyword (expr)
matchbeep variable (tcsh)
mattrib command
mbadblocks command
MBR (master boot record)
pre-Linux Windows version, restoring
mcat command
mcd command
mcopy command
md5crypt command (GRUB)
mdel command
mdelete command (ftp)
mdeltree command
mdir command
ftp
mdu command
memory information, displaying (vmstat)
memory usage information, accessing (free)
menu panels (GNOME)
merge command
merging model (CVS)
mesg command
Meta-key (Emacs)
commands
metacharacters 2nd
pattern matching vs. filename expansion
programs, listing by
metamail command
metasend command
mformat command
mget command (ftp)
Microsoft [See MS-DOS Windows]
MIME types
GNOME, setting in
mailto command
metamail command
metasend command
mimencode command
minfo command
minus (-) operator
mkdir command
ftp
mkdosfs command
mke2fs command
mkexrc command (ex)
mkfifo command
mkfs command
mkfs.ext2 command [See mke2fs command]
mkfs.ext3 command
mkfs.minix command
mkfs.msdos command [See mkdosfs command]
mkisofs command
mklost+found command
mknod command
mkpasswd command
mkraid command
mkswap command
mktemp command
mktime command (gawk)
mlabel command
mls command (ftp)
mmd command
mmount command
mmove command
mode command (ftp)
modinfo command
modprobe command
depmod and
modtime command (ftp)
module command (GRUB)
modulenounzip command (GRUB)
modules
fvwm2
KDE
loaded, listing of (lsmod)
loading (insmod)
loading with initrd
modulo (%) operator
more command
mount command 2nd
mountd command
mountd daemon
mouse accessibility settings (GNOME)
mouse commands (gpm)
move command (ex)
mpartition command
mpg123 command
mpg321 command
mput command (ftp)
mrd command
mren command
MS-DOS
booting from
changing directories on
disk usage, displaying
disks, formatting for
files
changing attributes of (mattrib)
deleting
filesystems
bad blocks, checking for
directory contents, listing (mdir)
formatting disks in (mformat)
restoring the pre-Linux MBR
mshowfat command
mt command
mtools commands
mtoolstest command
mtype command
Multiboot Specification
mv command
mzip command

Team LiB Previous Section


index_N

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

n command (sed)
N command (sed)
Name keyword (RCS)
name servers
name service
named command
named daemon 2nd
namei command
nameif command
netfilter
netstat command 2nd
network administration
commands
arp
NFS and NIS administration
TCP/IP troubleshooting
Network File System [See NFS]
Network Information System [See NIS]
networking commands
networks
file transfers between [See ftp]
securing remote connections cryptographically (ssh)
status messaging (rwhod)
new command (ex)
newaliases command
newer command (ftp)
newgrp command
tcsh
newusers command
next command
ex
gawk
nextfile command (gawk)
NFS (Network File System)
administration commands
daemons
NFS/NIS commands
domainname
makedbm
rpc.yppasswdd command
showmount
ypbind
ypcat
ypchfn
ypinit
ypmatch
yppasswd
yppoll
yppush
ypserv
ypset
yptest
ypwhich
ypxfr
nfsd command
nfsd daemons
nfsstat command
nice command
tcsh
NIS (Network Information System)
administration
administration commands
clients, setting up
map manipulation utilities
maps
servers, setting up
user accounts
nlist command (ftp)
nm command
nmap command (ftp)
nobeep variable (tcsh)
noclobber variable (tcsh)
noding variable (tcsh)
noglob variable (tcsh)
nohlsearch command (ex)
nohup command
nohup command (tcsh)
nokanji variable (tcsh)
nonomatch variable (tcsh)
NOREBIND environment variable (tcsh)
nostat variable (tcsh)
notify command (tcsh)
notify job control command (tcsh)
notify variable (tcsh)
nroff command, managing output with col, colcrt
nslookup command [See also dig command]2nd
nsupdate command
ntrans command (ftp)
null command (:)
number command (ex)
numbers, base conversions using bc
nvi text editor

Team LiB Previous Section


index_O

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

objcopy command
objdump command
Objective-C programming language, compiling (gcc)
od command
onintr command (tcsh)
online documentation
open command
ex
ftp
open source software [See free software]
OpenSSH
scp command
openvt command
option argument syntax
options to Linux commands
or command (gawk)
ORBit library
OSTYPE environment variable (tcsh)
output formatting commands
fmt
fold
owd variable (tcsh)

Team LiB Previous Section


index_P

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

p command (sed)
P command (sed)
package flags (Debian)
package managers [See also Debian package manager; RPM]2nd
pager (KDE)
pager command (GRUB)
paging commands
bzless
bzmore
less [See less program]
more
zless
zmore
panel (KDE)
parentheses ( )
escaped \( \)
partitioning
fdisk command
hard disks (cfdisk command)
partnew command (GRUB)
parttype command (GRUB)
passwd command
password command (GRUB)
passwords
KDE, setting in 2nd
managing
chage command
chfn command
chpasswd
paste command
patch command
PATH environment variable (tcsh)
path variable (tcsh)
pathchk command
pattern addressing (sed)
pattern matching
vs. filename expansion
foreign languages and
gawk [See gawk scripting language]
POSIX characters and
pause command (GRUB)
PCMCIA sockets
card daemon
controlling with cardctl command
percent (%)
bash job ID argument
prompt
perl command
Perl scripts for Debian package management
pidof command
ping command
pipe (|) 2nd
plus (+) operator
fvwm2
point (Emacs)
Point-to-Point Protocol (PPP) 2nd
popd command
bash
tcsh
Popup function (fvwm2)
portmap command
portmap daemon
POSIX character lists
poweroff command
PPP (Point-to-Point Protocol) 2nd
pppd command
pppd daemon
pr command
pragma directives (gcc)
praliases command
preserve command (ex)
previous command (ex)
print command
ex
gawk
print queue status, showing
print spool queue, checking (lpq)
printenv command
tcsh
printexitvalue variable (tcsh)
printf command
bash
gawk
printing commands 2nd
banner
checkpc
line printer parameters, controlling (tunelp)
lpc
lpd
lpq
lpr
lpstat
removing jobs from the queue (lprm)
processes
killing 2nd
pending jobs, deleting
pending jobs, listing
setting execution times for
program addresses, translation from hexadecimal to filenames
program maintenance commands
programming languages
gcc compiler
source files, inspection, editing (ctags)
programs, listing required libraries for (ldd)
prompt command (ftp)
prompt variables (tcsh)
formatting substitutions
promptchars variable (tcsh)
prompts
proxies
proxy command (ftp)
ps command
pserver access method (CVS)
pserver command (CVS)
pushd command
bash
tcsh
pushdsilent variable (tcsh)
pushdtohome variable (tcsh)
put command
ex
ftp
pwck command
pwconv command
pwd command
bash
ftp
PWD environment variable (tcsh)
pwunconv command
python command

Team LiB Previous Section


index_Q

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

q command (sed)
qall command (ex)
Qt
question mark (?) 2nd
double question marks
ftp help command
quit command
ex
ftp
GRUB
quota command
quote command (ftp)
quote keyword (expr)
quotes
quoting

Team LiB Previous Section


index_R

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

r command (sed)
raidstart command
raidstop command
RAM disks, configuring support for
ramsize command
rand command (gawk)
ranlib command
rannotate command (CVS) 2nd
RARP (Reverse Address Resolution Protocol) 2nd [See also ARP]
rarp command (GRUB)
rarpd command
raw command
rcp command
RCS (Revision Control System)
basic operations
commands
alphabetical summary
environment variables
keyword substitution
options
revision numbering
state
timestamps
rcs command (RCS) 2nd
rcsclean command (RCS)
rcsdiff command (RCS)
RCSfile keyword (RCS)
RCSINIT environment variable (RCS)
rcsmerge command (RCS)
rdate command
rdev command
rdiff command (CVS)
rdist command
rdistd command
read command
bash
ex
GRUB
readelf command
readlink command
readonly command (bash)
reboot command
GRUB
recexact variable (tcsh)
recognize_only_executables variable (tcsh)
recover command (ex)
recv command (ftp)
Red Hat Package Manager [See RPM]
redirection operators
redo command (ex)
reget command (ftp)
regular expressions
rehash command (tcsh)
Reiser FS (Reiser Filesystem)
embed command (GRUB)
relational operators (expr)
release command (CVS)
Remote Procedure Call [See RPC]
remotehelp command (ftp)
REMOTEHOST environment variable (tcsh)
remotestatus command (ftp)
removable media, ejecting
remove command (CVS)
rename command
ftp
renice command
repeat command (tcsh)
repositories (CVS)
creating
reset command 2nd [See also tset command]
ftp
resize command (ex)
resize2fs command
resolvers
restart command (ftp)
return command
bash
gawk
Return command (ex)
rev command
Reverse Address Resolution Protocol (RARP)
revision control 2nd [See also RCS; CVS]
Revision Control System [See RCS]
Revision keyword (RCS)
rewind command (ex)
rexecd command
richtext command
right command (ex)
ÒrippingÓ audio CDs
rlog command
CVS
RCS
rlogin command
rlogind command
rm command
rmail command
rmdir command
ftp
rmmod command
rmstar variable (tcsh)
root command (GRUB)
rootflags command
rootnoverify command (GRUB)
route command
routed command
routed daemon
routing daemons
routing tables
RPC (Remote Procedure Call)
rpc.mountd command
rpc.nfsd command
rpc.portmap command
rpc.rusersd command
rpc.statd command [See statd command]
rpcgen command
rpcinfo command
RPM (Red Hat Package Manager)
rpm command [See rpm command]
rpm command 2nd
configuration files
database rebuild options
downloading packages off the internet
examples
FTP/HTTP options
information selection options
install/upgrade options
package selection options
query options
signature check options
uninstall options
verify options
rpmbuild command
rprompt variable (tcsh)
rsh command
rshd command
rshift command (gawk)
rtag command (CVS)
run-parts command
runique command (ftp)
runlevel command
runlevels
changing (telinit)
rup command
ruptime command
rusers command
rusersd command
rwall command
rwho command
rwhod command

Team LiB Previous Section


index_S

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

s command (sed)
sandboxes (CVS)
savedefault command (GRUB)
savedirs variable (tcsh)
savehist variable (tcsh)
sbnext command (ex)
sbuffer command (ex)
sched command (tcsh)
sched variable (tcsh)
scheme command
scp command
screen command
script command
ex
scripts, Debian package management
SCSI drives, designation as devices
sdiff command
search commands
egrep
expr
fgrep (file searching)
find
grep
locate
look
whereis
zgrep
searching 2nd [See also pattern matching]
and replacing
vi editor, in
Second Extended Filesystem [See ext2]
security
APM (Advanced Power Management) and
Crypto module (KDE)
CVS and
encryption (ssh)
firewalls
GRUB configuration file and
ipchains command
iptables command
login manager (KDE)
passwords module (KDE)
sed command [See sed editor]
sed editor 2nd
commands
alphabetical listing
branching commands
editing
input/output processing
line information
multiline input processing
syntax
yanking and putting
invocation
pattern addressing
select command (bash)
semicolon (;)
send command (ftp)
sendmail command
sendport command (ftp)
seq command
serial command (GRUB)
Serial Line IP (SLIP)
serial-line communication
serial-lines, attaching as network interfaces (slattach)
server command (CVS)
set command
bash
ex 2nd
colon in (:set)
tcsh
setenv command (tcsh)
setfdprm command
setkey command (GRUB)
setkeycodes command
setleds command
setmetamode command
setsid command
settc command (tcsh)
setterm command
setty command (tcsh)
setup command (GRUB)
sftp command
sh command [See also bash shell]2nd
shar command
shell archives
creating (shar)
unpacking
shell command (ex)
shell commands
SHELL environment variable (tcsh)
shell scripts
comment character (#)
Debian package management
shell variables, tcsh shell
shells
bash [See bash shell]
C shell (tcsh)
common features
creating for user (su)
default, setting in /etc/passwd
shell variables
tcsh [See tcsh shell]
shift command
bash
tcsh
SHLVL environment variable (tcsh)
shlvl variable (tcsh)
shopt command (bash)
showkey command
showmount command
shred command
shutdown command
Simple Mail Transport Protocol (SMTP)
Simple Network Management Protocol (SNMP)
sin command (gawk)
site command (ftp)
size command
ftp
skill command
slattach command
sleep command
sliding panels (GNOME)
SLIP (Serial Line IP)
SMTP (Simple Mail Transport Protocol)
snext command (ex)
snice command [See also skill command]2nd
SNMP (Simple Network Management Protocol)
sort command
sound configuration
GNOME
KDE
source code
source command
bash
ex
tcsh
Source keyword (RCS)
spacing and syntax 2nd
special characters [See also pattern matching]2nd
splashimage command (GRUB)
split command
ex
gawk
sprevious command (ex)
sprintf command (gawk)
sqrt command (gawk)
srand command (gawk)
ssh program
ssh-add command
ssh-agent command
ssh-keygen command
ssh-keyscan command
sshd command [See also ssh program]2nd
SSL (Secure Sockets Layer), configuration in KDE
Stallman, Richard
stat command
statd command
state
State keyword (RCS)
status command
CVS
ftp
status variable (tcsh)
stop command
ex
tcsh 2nd
storage commands
strace command
stream editor [See sed editor]
strfile command
strftime command (gawk)
string matches, searching files for (look)
string searches with apropos
strings command
strip command
strtonum command (gawk)
struct command (ftp)
stty command
su command
sub command (gawk)
subdomains
substitute command (ex)
substr command (gawk)
substr keyword (expr)
sudo command
sum command
sunique command (ftp)
SuSE package manager [See RPM]
suspend command
bash
ex
tcsh
sview command (ex)
swapoff command
swapon command
switch command (tcsh)
symlinks variable (tcsh)
sync command
syntax, spacing and
sysctl command
sysklogd command
syslogd command [See sysklogd command]
system
information, displaying (uname)
logged-in users, displaying (who)
status, displaying (uptime)
system administration
commands
agetty
apmd
atd
badblocks
cardctl
cardmgr
cfdisk
chat
checkpc
chpasswd
chroot
clocks
cron
daemons
debugfs
depmod
dip
dmesg
dnssec-keygen
dnssec-makekeyset
dnssec-signkey
dnssec-signzone
dosfsck
dumpe2fs
e2fsck
e2image
e2label
elvtune
fdisk
fetchmail
filesystems management
fsck
fsck.minix
gpm
groupadd
groupdel
groupmod
grpck
grpconv and grpunconv
halt
host
hwclock
init
insmod
install
installation
ipchains
ipchains-restore
ipchains-save
ipcrm
ipcs
iptables
iptables-restore
iptables-save
kbdrate
kernel management
klogd
ksysms
lastlog
ldconfig
logrotate
losetup
lpc
lsmod
mailq
mailstats
makemap
mkdosfs
mke2fs
modprobe
networking
printing
rusersd
sendmail
setkeycodes
setsid
shutdown
statd
swapoff
swapon
sync
sysctl
sysklogd
telnit
tune2fs
tunelp
umount
update
user management
useradd
userdel
usermod
vidmode
zdump
zic
system calls, tracing (strace)
system command
ftp
gawk
system status commands
load average, displaying (tload)
top
usage information, displaying (w)
systime command (gawk)

Team LiB Previous Section


index_T

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

t command
ex
sed
Tab
tac command
tag command
CVS
ex
tags command (ex)
tail command
talk command
talkd command
tar command
taskbar (KDE)
tbl command, managing ouput with col, colcrt
TCP/IP (Transmission Control Protocol/Internet Protocol)
commands
arp
bootpd
bootptest
dnsdomainname
fingerd
ftpd command
identd
ifconfig
inetd
logger
lpd
ruptime
rusers
rwall
rwhod
slattach
sshd
talkd
tcpd
telnetd
tftpd
traceroute
xinetd
configuring
gateways and routing
included protocols
IP addresses
name service
troubleshooting commands
tcpd command
tcsh command
tcsh prompt
tcsh shell 2nd
arithmetic operators
assignment operators
bash, compared to
bitwise and logical operators
built-in commands
command completion
command history
command substitution
history modifiers
special aliases
word substitution
command structure
command-line editing
Emacs mode
vi mode
comparison operators
configuration files
environment variables
expressions
operator precedence
operators
file inquiry operators
formatting substitutions, prompt variable
invocation, options and arguments
job control commands
multiple redirection
quoting
characters
redirection
shell variables
special characters
special files
syntax
variables
modifiers
variable substitution
tcsh variable (tcsh)
tee command
telinit command
telltc command (tcsh)
telnet command
telnetd command
tenex command (ftp)
TERM environment variable (tcsh)
term variable (tcsh)
TERMCAP environment variable (tcsh)
terminal command (GRUB)
terminal configuration (setterm)
terminal display, clearing
terminal emulators
ANSI/VT100 emulation, enabling (screen)
Konsole (KDE) 2nd
terminal sessions, recording (script)
terminals
displaying name of (tty)
I/O options setting (stty)
initializing (tset)
test command
bash
testload command (GRUB)
testvbe command (GRUB)
text editors
dual mode vs. modeless editing
Emacs [See Emacs editor]
ex [See ex editor]
pattern matching in
sed [See sed editor]
vi [See vi editor]
tftp command
tftpd command
tftpserver command (GRUB)
Third Extended Filesystem [See ext3]
tilde (~)
bash
ex command
gawk
sed command
tcsh
time and date commands
cal
date
time command
time command (tcsh)
time variable (tcsh)
times command (bash)
timezones, displaying data about
tload command
TLS (Transport Layer Security), configuration in KDE
tolower command (gawk)
top command
top-level domains
Torvalds, Linus
touch command
toupper command (gawk)
tperiod variable (tcsh)
tr command
trace command (ftp)
traceroute command
tracing system calls (strace)
trap command (bash)
troff command [See groff command]
TrollTech, Inc.
true command [See also false command]2nd
tset command
tty command
tty variable (tcsh)
tune2fs command
tune2fs utility
ext2, converting to ext3
tunelp command
type command
bash
ftp
typeset command (bash) [See declare command]
Team LiB Previous Section


index_U

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

UDP (User Datagram Protocol)
uid variable (tcsh)
ul command
ulimit command (bash)
umask command
bash
ftp
tcsh
umount command
unabbreviate command (ex)
unalias command
bash
tcsh
uname command
uncomplete command (tcsh)
uncompress command
uncompressing and paging (zmore)
undo command (ex)
unedit command (CVS)
unexpand command
unhash command (tcsh)
unhide command
ex
GRUB
unicode_start command
unicode_stop command
uniq command
Unix shell command (sh)
Unix, compared to Linux
unlimit command (tcsh)
unmap command (ex)
unset command
bash
tcsh
unsetenv command (tcsh)
unshar command
unstr command [See strfile command]
until command (bash)
update command
CVS
uppermem command (GRUB)
uptime command
Usenet newsgroups
user command (ftp)
USER environment variable (tcsh)
user login times, tracking (ruptime)
user variable (tcsh)
useradd command
userdel command
usermod command
users
finding login names for
management commands
users command
usleep command
uudecode command
uuencode command
uuidgen command
UUIDs (Universal Unique Identifiers), creating (uuidgen)

Team LiB Previous Section


index_V

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

v command (ex)
vacation command
variables, gawk scripting language
usage in
vbeprobe command (GRUB)
vdir command
VENDOR environment variable (tcsh)
verbose command (ftp)
verbose variable (tcsh)
version command
CVS
ex
version control 2nd [See also RCS; CVS]
version variable (tcsh)
vi command (ex)
vi editor 2nd
address symbols
bindings, compared to Emacs bindings
command mode
alphabetical key list
command syntax
command-line editing mode (bash) 2nd
command-line options
configuration
~/.exrc file 2nd
edit commands
changing text
deleting text
exiting
multiple files
saving
text insertion
editing operators
enhanced versions
ex [See ex editor]
files, opening
insert mode
line numbering
macros
marking position
miscellaneous commands
movement commands
character
lines
screens
text
operating modes
searching
:set command (ex)
shell, interacting with
starting a session
status-line commands
tcsh command-line editing mode
user-defined commands, characters for
window commands
vidmode command
view command (ex)
vile text editor
vim command [See vi editor]
vim editor
virtual consoles
destroying
number of, determining
virtual terminals, switching between
visiblebell variable (tcsh)
visual command (ex)
VISUAL environment variable
bash
tcsh
viusage command (ex)
vmstat command
volname command
vsplit command (ex)

Team LiB Previous Section


index_W

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

w command
sed
wait command
bash
tcsh
wall command
ex
warning options, gcc
watch command
CVS
watch variable (tcsh)
watchers command (CVS)
watchlog command (tcsh)
wc command
web browsers (KDE) 2nd
web sites
whatis command
whatis database, searching with apropos command
where command (tcsh)
whereis command
which command
tcsh
while command
bash
gawk
tcsh
whitespace, converting to tabs (unexpand)
who command
who variable (tcsh)
whoami command
whois command
Window List Applet (GNOME)
window managers
windows (Emacs)
Windows (Microsoft)
dual booting, NT/2000/XP and Linux
restoring the pre-Linux MBR
share configuration (KDE)
wnext command (ex)
wordchars variable (tcsh)
working directories
CVS
pwd command, identifying with
Workspace Switcher Applet (GNOME)
wq command (ex)
wqall command (ex)
write command
ex

Team LiB Previous Section


index_X

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

X command (ex)
x command (sed)
X Window System
xargs command
XDR (eXternal Data Representation)
XFS (Extensible Filesystem)
Ximian Red Carpet
Xinerama 2nd
xinetd command
xit command (ex)
xor command (gawk)

Team LiB Previous Section


index_Y

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

y command (sed)
yacc command
yank command
Emacs
ex
yes command
ypbind command
ypcat command
ypchfn command
ypinit command 2nd
ypmatch command
yppasswd command
yppasswdd command
yppoll command
yppush command 2nd
ypserv command
ypset command
yptest command
ypwhich command
ypxfr command

Team LiB Previous Section


index_Z

Team LiB Previous Section
[SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] [Z]

z command (ex)
Z shell
zcat command
zcmp command
zdiff command
zdump command
zforce command
zgrep command
zic command
zless command
zmore command
znew command

Team LiB Previous Section