Linux in a Nutshell, 5th Edition

Next Page

Book Cover
Linux in a Nutshell, 5th Edition
By Stephen Figgins, Robert Love, Arnold Robbins, Ellen Siever, Aaron Weber
...............................................
Publisher: O'Reilly
Pub Date: July 2005
ISBN: 0-596-00930-5
Pages: 944

Table of Contents | Index
Overview

Over the last few years, Linux has grown both as an operating system and a tool for personal and business use. Simultaneously becoming more user friendly and more powerful as a back-end system, Linux has achieved new plateaus: the newer filesystems have solidified, new commands and tools have appeared and become standard, and the desktop--including new desktop environments--have proved to be viable, stable, and readily accessible to even those who don't consider themselves computer gurus.

Whether you're using Linux for personal software projects, for a small office or home office (often termed the SOHO environment), to provide services to a small group of colleagues, or to administer a site responsible for millions of email and web connections each day, you need quick access to information on a wide range of tools. This book covers all aspects of administering and making effective use of Linux systems. Among its topics are booting, package management, and revision control. But foremost in Linux in a Nutshell are the utilities and commands that make Linux one of the most powerful and flexible systems available.

Now in its fifth edition, Linux in a Nutshell brings users up-to-date with the current state of Linux. Considered by many to be the most complete and authoritative command reference for Linux available, the book covers all substantial user, programming, administration, and networking commands for the most common Linux distributions.

Comprehensive but concise, the fifth edition has been updated to cover new features of major Linux distributions. Configuration information for the rapidly growing commercial network services and community update services is one of the subjects covered for the first time.

But that's just the beginning. The book covers editors, shells, and LILO and GRUB boot options. There's also coverage of Apache, Samba, Postfix, sendmail, CVS, Subversion, Emacs, vi, sed, gawk, and much more. Everything that system administrators, developers, and power users need to know about Linux is referenced here, and they will turn to this book again and again.

Next Page


Table of Contents

Previous Page

Book Cover
Linux in a Nutshell, 5th Edition
By Stephen Figgins, Robert Love, Arnold Robbins, Ellen Siever, Aaron Weber
...............................................
Publisher: O'Reilly
Pub Date: July 2005
ISBN: 0-596-00930-5
Pages: 944

Table of Contents | Index

Copyright
Preface
 | Organization of This Book
 | Other Resources
 | Using Code Examples
 | Conventions
 | Safari® Enabled
 | How to Contact Us
 | Acknowledgments
Chapter 1. Introduction
 | Section 1.1. The Excitement of Linux
 | Section 1.2. Distribution and Support
 | Section 1.3. Commands on Linux
 | Section 1.4. What This Book Offers
 | Section 1.5. Sources and Licenses
 | Section 1.6. Beginner's Guide
Chapter 2. System and Network Administration Overview
 | Section 2.1. Common Commands
 | Section 2.2. Overview of Networking
 | Section 2.3. Overview of TCP/IP
 | Section 2.4. Overview of Firewalls and Masquerading
 | Section 2.5. Overview of NFS
 | Section 2.6. Overview of NIS
 | Section 2.7. Administering NIS
 | Section 2.8. RPC and XDR
Chapter 3. Linux Commands
 | Section 3.1. Alphabetical Summary of Commands
Chapter 4. Boot Methods
 | Section 4.1. The Boot Process
 | Section 4.2. LILO: The Linux Loader
 | Section 4.3. GRUB: The Grand Unified Bootloader
 | Section 4.4. GRUB Commands
 | Section 4.5. Dual-Booting Linux and Windows NT/2000/XP
 | Section 4.6. Boot-Time Kernel Options
 | Section 4.7. initrd: Using a RAM Disk
Chapter 5. Package Management
 | Section 5.1. The Red Hat Package Manager
 | Section 5.2. Yum: Yellowdog Updater Modified
 | Section 5.3. up2date: Red Hat Update Agent
 | Section 5.4. The Debian Package Manager
Chapter 6. The Bash Shell and Korn Shell
 | Section 6.1. Overview of Features
 | Section 6.2. Invoking the Shell
 | Section 6.3. Syntax
 | Section 6.4. Functions
 | Section 6.5. Variables
 | Section 6.6. Arithmetic Expressions
 | Section 6.7. Command History
 | Section 6.8. Job Control
 | Section 6.9. Command Execution
 | Section 6.10. Restricted Shells
 | Section 6.11. Built-in Commands (Bash and Korn Shells)
Chapter 7. Pattern Matching
 | Section 7.1. Filenames Versus Patterns
 | Section 7.2. Metacharacters
 | Section 7.3. Metacharacters, Listed by Program
 | Section 7.4. Examples of Searching
Chapter 8. The Emacs Editor
 | Section 8.1. Conceptual Overview
 | Section 8.2. Command-Line Syntax
 | Section 8.3. Summary of Commands by Group
 | Section 8.4. Summary of Commands by Key
 | Section 8.5. Summary of Commands by Name
Chapter 9. The vi, ex, and vim Editors
 | Section 9.1. Conceptual Overview
 | Section 9.2. Command-Line Syntax
 | Section 9.3. Review of vi Operations
 | Section 9.4. vi Commands
 | Section 9.5. vi Configuration
 | Section 9.6. ex Basics
 | Section 9.7. Alphabetical Summary of ex Commands
Chapter 10. The sed Editor
 | Section 10.1. Conceptual Overview
 | Section 10.2. Command-Line Syntax
 | Section 10.3. Syntax of sed Commands
 | Section 10.4. Group Summary of sed Commands
 | Section 10.5. Alphabetical Summary of sed Commands
Chapter 11. The gawk Programming Language
 | Section 11.1. Conceptual Overview
 | Section 11.2. Command-Line Syntax
 | Section 11.3. Patterns and Procedures
 | Section 11.4. Built-in Variables
 | Section 11.5. Operators
 | Section 11.6. Variable and Array Assignment
 | Section 11.7. User-Defined Functions
 | Section 11.8. Gawk-specific Features
 | Section 11.9. Implementation Limits
 | Section 11.10. Group Listing of awk Functions and Commands
 | Section 11.11. Alphabetical Summary of awk Functions and Commands
 | Section 11.13. Source Code
Chapter 12. Source Code Management: An Overview
 | Section 12.1. Introduction and Terminology
 | Section 12.2. Usage Models
 | Section 12.3. Source Code Management Systems
 | Section 12.4. Other Source Code Management Systems
Chapter 13. The Concurrent Versions System (CVS)
 | Conceptual Overview
 | Command-Line Syntax and Options
 | Dot Files
 | Environment Variables
 | Keywords and Keyword Modes
 | Dates
 | CVSROOT Variables
 | Alphabetical Summary of Commands
Chapter 14. The Subversion Version Control System
 | Section 14.1. Conceptual Overview
 | Section 14.2. Obtaining Subversion
 | Section 14.3. Using Subversion: A Quick Tour
 | Section 14.4. The Subversion Command Line Client: svn
 | Section 14.5. Repository Administration: svnadmin
 | Section 14.6. Examining the Repository: svnlook
 | Section 14.7. Providing Remote Access: svnserve
 | Section 14.8. Other Subversion Components
Colophon
 | About the Authors
 | Colophon
Index

Previous Page


Copyright

Linux in a Nutshell, Fifth Edition

by Ellen Siever, Aaron Weber, Stephen Figgins, Robert Love, and Arnold Robbins

Copyright © 2005, 2003, 2000, 1999, 1997 O'Reilly Media, Inc. All rights reserved.

Printed in the United States of America.

Published by O'Reilly Media, Inc. 1005 Gravenstein Highway North Sebastopol, CA 95472.

O'Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (safari.oreilly.com). For more information, contact our corporate/institutional sales department: 800-998-9938 or corporate@oreilly.com.

Editor: | Andy Oram
Production Editor: | Sanders Kleinfeld
Cover Designer: | MendeDesign, www.mendedesign.com
Cover Designer: | Edie Freedman
Interior Director: | David Futato
Printing History: |
January 1997: | First Edition.
February 1999: | Second Edition.
August 2000: | Third Edition.
June 2003: | Fourth Edition.
July 2005: | Fifth Edition.

Nutshell Handbook, the Nutshell Handbook logo, and the O'Reilly logo are registered trademark of O'Reilly Media, Inc. The In a Nutshell series designations, Linux in a Nutshell, the image of an Arabian horse, and related trade dress are trademarks of O'Reilly Media, Inc.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O'Reilly Media, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps.

While every precaution has been taken in the preparation of this book, the publisher and author assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

ISBN: 0-596-00930-5


Preface

This is a book about Linux, a freely available clone of the Unix operating system whose uses range from embedded systems and personal data assistants (PDAs) to corporate servers, web servers, and massive clusters that perform some of the world's most difficult computations.

Whether you are using Linux for personal software projects, for a small office or home office (the so-called SOHO environment), to provide services to a small group of colleagues, or to administer a site responsible for millions of email and web connections each day, you need quick access to information on a wide range of tools. This book covers all aspects of administering and making effective use of Linux systems. Among its topics are booting, package management, and revision control. But foremost in Linux in a Nutshell are the immeasurable utilities and commands that make Linux one of the most powerful and flexible systems available.

In addition to the tools and features written specifically for it, Linux has inherited many from the Free Software Foundation's GNU project, the Berkeley Software Distribution (BSD), the X Window System, and contributions from major corporations as well as the companies that created the major Linux distributions. More recent projects extend Linux in exciting ways, some through changes to the kernel and some through libraries and applications that radically change the user's experience.

This book is a quick reference for the basic commands and features of the Linux operating system. As with other books in O'Reilly's "In a Nutshell" series, this book is geared toward users who know what they want to do and have some idea how to do it, but can't always remember the correct command or option. The fifth edition has been examined from start to end and checked against the most common Linux distributions (Debian, Fedora, and SUSE) so that it reflects the most useful and popular commands.


Organization of This Book

This book is a reference to the most important commands and utilities available on Linux systems.

Chapter 1, Introduction, explains Linux's strengths and the key aspects of working with Linux, and lays out the scope of this book.

Chapter 2, System and Network Administration Overview, introduces TCP/IP networking and the Linux commands used for system administration and network management.

Chapter 3, Linux Commands, is the core of the book, a reference listing of hundreds of the most important shell commands available on Linux.

Chapter 4, Boot Methods, covers the commands used to control booting on Linux and dual-booting, particularly LILO, GRUB, and initrd.

Chapter 5, Package Management, explains the apt series of commands that manage updating and installation on Debian, and the RPM system used by Red Hat/Fedora, Novell/SUSE, and several other distributions of Linux.

Chapter 6, The Bash Shell and Korn Shell, documents the default command-line interpreter on Linux, Bash, and another popular interpreter, ksh.

Chapter 7, Pattern Matching, introduces regular expressions and explains how different tools interpret these powerful tools for searching and text processing.

Chapter 8, The Emacs Editor, provides reference information on Emacs, a text editor and full-featured development environment.

Chapter 9, The vi, ex, and vim Editors, describes the classic vi editor that is the most popular text-manipulation tool on Linux.

Chapter 10, The sed Editor, describes this "stream editor" that is useful for processing files in standardized ways.

Chapter 11, The gawk Programming Language, documents another valuable tool for processing text files, the GNU version of awk that is the default on Linux systems.

Chapter 12, Source Code Management: An Overview, provides the background for understanding CVS and Subversion, which are valuable tools for tracking changes to files and projects, and are discussed in the following two chapters.

Chapter 13, The Concurrent Versions System (CVS), provides a description of a popular source code management and version-control tool.

Chapter 14, The Subversion Version Control System, describes what is generally considered the next generation of CVS.


Other Resources

This book doesn't tell you how to install and get up to speed on a Linux system. For that, you will probably want O'Reilly's Running Linux, an in-depth guide suitable for all major distributions. For networking information, check out Linux Network Administrator's Guide (O'Reilly). In addition to these and other Linux titles, O'Reilly's wide range of Unix, X, web-related, and scripting and programming language titles may also be of interest to the Linux user.

Online Documentation

The Internet is full of information about Linux. One of the best resources is the Linux Documentation Project at http://www.tldp.org (or one of the dozens of mirror sites around the world), which has numerous short guides called HOWTOs, along with some full manuals. For online information about the GNU utilities covered in this book, consult http://www.gnu.org (also widely mirrored). The Free Software Foundation, which is in charge of the GNU project, publishes its documentation in a number of hardcopy and online books about various tools.

Each distribution maintains its own web site, and contains documentation for the software it provides as well as guides to maintaining your system under that distribution.

Web Sites

As befits a hot phenomenon, Linux is the central subject of several web sites and a frequent topic of discussion on others. Some sites offer original content; others just have links to articles posted elsewhere and threaded discussions (which can be a useful service). Among the sites frequented by Linux users are:

http://lwn.net

Linux Weekly News, a site with weekly in-depth articles and frequent news updates

http://www.linuxgazette.net

Linux Gazette, a site published monthly with articles and tips in many languages

http://www.linuxquestions.org

A very popular source for technical guidance, including a growing Wiki (site maintained by user contributions) at http://wiki.linuxquestions.org

http://www.tuxmagazine.com

TUX, an online magazine focusing on tools and techniques for desktop Linux users

http://linuxsecurity.com

Linux Security, a collection of security-related news

http://linuxinsider.com

Linux Insider, a news feed

http://linuxtoday.com

Linux Today, another news feed

http://slashdot.org

Slashdot, a famous discussion list

http://newsforge.com

NewsForge, a more general computing-related news feed

Linux Journal and Linux Magazine

Linux Journal and Linux Magazine are monthly magazines for the Linux community, written and published by a number of Linux activists. With both print editions and web sites, they offer articles ranging from questions and answers for novices to kernel programming internals. Linux Journal, at http://www.linuxjournal.com, is the older magazine and is published by S.S.C. Incorporated, http://www.ssc.com. Linux Magazine is at http://www.linuxmagazine.com.

Usenet Newsgroups

Most people can receive Usenet news at work or through their ISPs. While this communications technology has lost ground in the past several years to web-based threaded discussions, it is still a valuable source of help and community connections on many topics. The following Linux-related newsgroups are popular:

comp.os.linux.announce

A moderated newsgroup containing announcements of new software, distributions, bug reports, and goings-on in the Linux community. All Linux users should read this group. Submissions may be mailed to linux-announce@news.ornl.gov.

comp.os.linux.development.apps

Guidance for using features of Linux for application development, and for understanding the effects of the operating system on user-space programs.

comp.os.linux.development.system

Discussions about developing the Linux kernel and the system itself.

comp.os.linux.networking

Discussions relating to networking with Linux.

comp.os.linux.x

Help on getting the X graphical window system to work. This list used to see some of the highest traffic of any Linux group back when distributions had more trouble setting up graphics automatically. This is no longer the case, thanks to the increasing sophistication of autodetection and configuration software.

There are also several newsgroups devoted to Linux in languages other than English, such as fr.comp.os.linux in French and de.comp.os.linux in German.

Online Linux Support

There are many ways of obtaining help online, where volunteers from around the world offer expertise and services to assist users with questions and problems.

The freenode IRC service is an Internet relay chat network devoted to so-called "peer-directed" projects, particularly those involving free software. Some of its channels are designed to provide online Linux support services.

Internet relay chat is a network service that allows you to talk interactively on the Internet to other users. IRC networks support multiple channels where different groups of people type their thoughts. Whatever you type in a channel is seen by all other users of that channel.

There are a number of active channels on the freenode IRC network, where you will find users 24 hours a day, 7 days a week who are willing and able to help you solve any Linux problems you may have, or just chat. You can use this service by installing an IRC client (some distributions install them by default), connecting to server name irc.freenode.org:6667, and joining a channel focusing on Linux, such as:

#linpeople

General help and discussion

#debian

Help for Debian distribution

#gentoo

Help for Gentoo distribution

#redhat

Help for Red Hat distribution

#suse

Help for SUSE distribution

And so on. Please be sure to read up on the rules of chat etiquette before chatting. In particular, the participants in these groups tend to expect people to read documentation and do some experimentation before asking for help with a problem.

Linux User Groups

Many Linux User Groups around the world offer direct support to users. Typically, Linux User Groups engage in such activities as installation days, talks and seminars, demonstration nights, and purely social events. Linux User Groups are a great way of meeting other Linux users in your area. There are a number of published lists of Linux User Groups. Some of the better-known ones are:

http://www.ssc.com/glue/groups

Groups of Linux Users Everywhere

http://www.linux.org/users

LUGregistry


Using Code Examples

This book is here to help you get your job done. In general, you may use the code in this book in your programs and documentation. You do not need to contact O'Reilly for permission unless you're reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O'Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product's documentation does require permission.

We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: "Linux in a Nutshell, by Ellen Siever, Aaron Weber, Stephen Figgins, Robert Love, and Arnold Robbins. Copyright 2005 O'Reilly Media, Inc., 0-596-00930-5."

If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact the publisher at permissions@oreilly.com.


Conventions

This desktop quick reference follows certain typographic conventions:

Bold

Used for commands, programs, and options. All terms shown in bold are typed literally.

Italic

Used to show arguments and variables that should be replaced with user-supplied values. Italic is also used to introduce new terms, indicate filenames and directories, and to highlight comments in examples.

Constant Width

Used to show the contents of files or the output from commands.

Constant Width Bold

Used in examples to show commands or other text that should be typed literally by the user.

Constant Width Italic

Used in examples to show text that should be replaced with user-supplied values.

$

Used in some examples as the bash shell prompt ($).

[ ]

Surround optional elements in a description of syntax. (The brackets themselves should never be typed.) Note that many commands show the argument [files]. If a filename is omitted, standard input (e.g., the keyboard) is assumed. End with an end-of-file character.

EOF

Indicates the end-of-file character (normally Ctrl-D).

|

Used in syntax descriptions to separate items for which only one alternative may be chosen at a time.

NOTE

This icon indicates a note, which is an important aside to its nearby text.

This icon indicates a warning.

A final word about syntax. In many cases, the space between an option and its argument can be omitted. In other cases, the spacing (or lack of spacing) must be followed strictly. For example, -wn (no intervening space) might be interpreted differently from -w n. It's important to notice the spacing used in option syntax.


Safari® Enabled

When you see a Safari® Enabled icon on the cover of your favorite technology book, it means the book is available online through the O'Reilly Network Safari Bookshelf.

Safari offers a solution that's better than e-books. It's a virtual library that lets you easily search thousands of top tech books, cut and paste code samples, download chapters, and find quick answers when you need the most accurate, current information. Try it for free at http://safari.oreilly.com.


How to Contact Us

We have tested and verified all of the information in this book to the best of our ability, but you may find that features have changed (or even that we have made mistakes!). Please let us know about any errors you find, as well as your suggestions for future editions, by writing:

O'Reilly Media, Inc.
1005 Gravenstein Highway North
Sebastopol, CA 95472
(800) 998-9938 (in the United States or Canada)
(707) 829-0515 (international or local)
(707) 829-0104 (fax)

There is a web page for this book, which lists errata, examples, or any additional information. You can access this page at:

http://www.oreilly.com/catalog/linuxnut5/

To comment or ask technical questions about this book, send email to:

bookquestions@oreilly.com

For more information about books, conferences, Resource Centers, and the O'Reilly Network, see the O'Reilly web site at:

http://www.oreilly.com


Acknowledgments

This fifth edition of Linux in a Nutshell is the result of the cooperative efforts of many people. Thanks to Andy Oram for his editorial skills, as well as for pitching in to check existing chapters and update and write new material as needed.

For technical review, thanks go to Robert J. Chassell, Matthias Kalle Dalheimer, Terry Dawson, Phil Hughes, Michael K. Johnson, Julian T. J. Midgley, Doug Moreen, Ron Passerini, Rick Rezinas, Chris Rivera, Bill Rushmore, James Stanger, Mark Stone, Laurie Lynne Tucker, and Matt Welsh.


Chapter 1. Introduction

It is hard to chart the rise of Linux without risking the appearance of exaggeration and hyperbole. During the past few 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 as complements to the development of the Linux kernel.

Linux systems cannot be technically referred to as a "version of Unix," as they have not undergone the required tests and licensing.[*] 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.

[*] 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) and Freshmeat (http://freshmeat.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 focal point 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.


Section 1.1. The Excitement of Linux

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 just free softwareit'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 it 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 Unixwhich newcomers usually found confusing and frustrating, but eventually found they couldn't live withoutcontinually inspired extensions, new tools, 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 togetherall 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 Linuxit makes efficient use of its resources.

For the first several years after its appearance, 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 provides stable Windows-based networking to a large number of end-user PCs. 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 growing in 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 many new commands found in this edition.


Section 1.2. Distribution and Support

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. Also, because of the vast number and variety of tools beyond the kernel required for a functional computing environment, building a Linux installation from scratch is quite complex. 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. Since then, CD-ROM drives have become widespread and sharing Linux has become much easier.

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).


Section 1.3. Commands on Linux

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 such as 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 and X.org projects to standard Intel chips. This book does not discuss the X Window System; see the O'Reilly book Running Linux for an introduction to X.


Section 1.4. What This Book Offers

1.4. What This Book Offers

Originally based on the classic O'Reilly 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)

  • Boot methods

  • The CVS and Subversion version control systems

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 (Sun Microsystems' free, open source version of the StarOffice suite), Evolution (a mail, calendar, and office productivity tool from Novell), Firefox and Mozilla (the open source cousins of the Netscape web browser), and the GIMP (a graphic image-manipulation program and provider of a powerful library used by 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 probably log in to one of the graphical desktop environments such as GNOME or KDE and do much of your 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 remains largely a command-driven system, and this book continues to focus on this level of usage; for many tasks, the command line is the most efficient and flexible tool. 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. There are variations in directory structure, choice of standard utilities, and software versions, 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. Note, though, that some commands are only available with certain devices or configurations, or have alternatives that may be preferred in your environment. 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 languagessuch as Java, Perl, and Pythonwith 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 Linuxit is, after all, a quick referencebut 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 shorter 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), many users opt for a dual-boot system, with Linux residing on the same computer as other operating systems. Users can then boot to the system they need for a particular job. Chapter 4 describes the commonly used booting options on Intel systems, including LILO (Linux Loader) and GRUB (the GRand Unified Bootloader). Chapter 5 covers the Red Hat package manager (rpm)--which is supported by many distributions, including Red Hat, SUSE, and Mandriva (formerly Mandrake)--and the Debian package-management system, which is used by such distributions as Knoppix, Gnoppix, and Ubuntu. It also describes some of the newer frontend package-management tools that simplify package management and automatically resolve dependencies. These tools include yum and up2date for rpm-based systems and aptitude and synaptic for Debian-based systems. 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, the standard shell is bash. Others, such as the ksh Korn shell, the tcsh enhanced C shell, and zsh, are available. Chapter 6 provides thorough coverage of bash and the Korn shell; you may decide to read this chapter after you've used Linux for a while, because it mostly covers powerful, advanced features that you'll want when you're a steady user. Chapter 7 covers pattern matching, which is used by the Linux text-editing utilities for searching based on a pattern rather than an explicit string.

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 8, and vi is discussed in Chapter 9. Chapter 9 also describes vim, an extended version of vi, commonly found on Linux systems. Chapter 10 and Chapter 11 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 known for being 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 Subversion 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 12 offers a brief overview of version control, including basic terms and concepts. Chapter 13 presents CVS commands, and Chapter 14 presents Subversion commands.

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 percent of the time. See the man command in Chapter 3 for information on reading the man pages. They can also be read with the info command, the GNU hypertext documentation reader, also documented in Chapter 3.


Section 1.5. Sources and Licenses

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 or made available 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 (FSF).

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 the creation of fast code. One of the most ambitious 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, withhold the source code, and then sell the product as proprietary software. Doing so would be taking advantage of the FSF and users of the GPL. You can find the text of 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 doesn'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.


Section 1.6. Beginner's Guide

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

Command | Action
dig | Query DNS server.
ftp | File Transfer Protocol.
login | Sign on.
rsync | Transfer files, particularly across a network.
scp | Securely copy files to remote system.
ssh | Run shell or single command on remote system (secure).
talk | Exchange messages interactively with other terminals.
tftp | Trivial File Transfer Protocol.

1.6.2. Comparisons

Command | Action
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.
sdiff | Compare and interactively merge two files.

1.6.3. File Management

Command | Action
cat | Concatenate files or display them.
chfn | Change user information for finger, email, etc.
chgrp | Change group of files.
chmod | Change access modes on files.
chown | Change ownership of files.
chsh | Change login shell.
cksum | Compute checksum.
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.
hexdump | Display files in hexadecimal format.
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.
od | Display files in octal format.
pwd | Print working directory.
rm | Remove files.
rmdir | Remove directories.
shred | Securely delete files.
split | Split files evenly.
tac | Print lines of a file in reverse order.
tail | Show the last few lines of a file.
tailf | Follow the growth of a logfile.
touch | Update file timestamps and create the file if it doesn't exist.
wc | Count lines, words, and characters.

1.6.4. Media

Command | Action
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.
mkisofs | Generate a binary image from a directory tree.
mpg321 | Play an MP3 file.
readcd | Read or write a data CD.
volname | Provide the volume name of a CD-ROM.

1.6.5. Printing

Command | Action
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

Command | Action
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.
ldd | Print shared library dependencies.
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

Command | Action
cvs | Manage different versions (revisions) of source files.
ctags | Generate symbol list for use with the vi editor.
etags | Generate symbol list for use with the Emacs editor.
gdb | GNU debugger.
gprof | Display object file's profile data.
make | Maintain, update, and regenerate related programs and files.
nm | Display object file's symbol table.
objcopy | Copy and translate object files.
objdump | Display information about object files.
patch | Apply patches to source code.
pmap | Print the memory map of a process.
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

Command | Action
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.
look | Search file for string at the beginning of lines.
strings | Search binary files for text patterns.
whereis | Find command.
which | Print pathname of a command.

1.6.9. Shell Programming

Command | Action
basename | Remove leading directory components from a path.
echo | Repeat command-line arguments on the output.
envsubst | Substitute the value of environment variables into strings.
expr | Perform arithmetic and comparisons.
mktemp | Generate temporary filename and create the file.
printf | Format and print command-line arguments.
sleep | Pause during processing.
test | Test a condition.

1.6.10. Storage

Command | Action
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.
tar | Copy files to or restore files from an archive medium.
zcat | Display contents of compressed files.
zforce | Force gzip files to have .gz extension.

1.6.11. System Status

Command | Action
at | Execute commands later.
atq | Show jobs queued by at.
atrm | Remove job queued by at.
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.
free | Show free and used memory.
hostname | Display the system's hostname.
kill | Terminate a running command.
printenv | Show environment variables.
ps | Show processes.
quota | Display disk usage and limits.
stat | Display file or filesystem status.
stty | Set or display terminal settings.
top | Display tasks currently running.
tty | Display filename of the terminal connected to standard input.
uname | Display system information.
uptime | Show how long the system has been running.
vmstat | Show virtual memory statistics.
who | Show who is logged in.

1.6.12. Text Processing

Command | Action
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.
groff | Format troff input.
gs | Display PostScript or PDF file.
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.
tr | Translate (redefine) characters.
uniq | Find repeated or unique lines in a file.
vi | Visual text editor.
vim | Enhanced version of vi.

1.6.13. Miscellaneous

Command | Action
banner | Make posters from words.
bc | Arbitrary precision calculator.
cal | Display calendar.
clear | Clear the screen.
info | Get command information from the GNU hypertext reader.
man | Get information on a command.
nice | Reduce a job's priority.
nohup | Preserve a running job after logging out.
openvt | Run a program on the next available virtual terminal.
passwd | Set your login password.
script | Produce a transcript of your login session.
su | Become a different user, often the superuser.
sudo | Execute an authorized command as root or another user.
tee | Simultaneously store output in file and send to screen.
time | Time the execution of a command
wall | Send a message to all terminals.
whoami | Print the current user id.
xargs | Process many arguments in manageable portions.


Chapter 2. System and Network Administration Overview

    Section 2.1. Common Commands

    Section 2.2. Overview of Networking

    Section 2.3. Overview of TCP/IP

    Section 2.4. Overview of Firewalls and Masquerading

    Section 2.5. Overview of NFS

    Section 2.6. Overview of NIS

    Section 2.7. Administering NIS

    Section 2.8. RPC and XDR


Section 2.1. Common Commands

2.1. Common Commands

Following are lists of commonly used system administration commands.

2.1.1. Clocks

Command | Action
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

Command | Action
apmd | Advanced Power Management daemon.
atd | Queue commands for later execution.
bootpd | Internet Boot Protocol daemon.
cupsd | Printer daemon.
fingerd | Finger daemon.
ftpd | File Transfer Protocol daemon.
imapd | IMAP mailbox server daemon.
klogd | Manage syslogd.
mountd | NFS mount request server.
named | Internet domain nameserver.
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.
xinetd | Extended Internet services daemon. Starts other services as needed.
ypbind | NIS binder process.
yppasswdd | NIS password modification server.
ypserv | NIS server process.

2.1.3. Hardware

Command | Action
agetty | Start user session at terminal.
arp | Manage the ARP cache.
cardctl | Control PCMCIA cards.
cardmgr | PCMCIA card manager daemon.
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

Command | Action
arch | Print machine architecture.
dig | Query Internet domain nameservers.
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.
uname | Print host information.

2.1.5. Installation

Command | Action
cpio | Copy files to and from 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

Command | Action
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.
newaliases | Rebuild sendmail's alias database.
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, USB drives, 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. By default, almost all modern distributions of Linux use a journaling filesystem. When the kernel interacts with a journalling 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.

Most current Linux distributions default to the Third Extended (ext3) Filesystem. The ext3 filesystem was developed primarily for Linux and supports 256-character filenames and 4-terabyte maximum filesystem size. This ext3 filesystem is essentially a Second Extended (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.

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. Other common filesystems include the FAT and VFAT filesystems, which allow files on partitions and floppies of Microsoft Windows systems to be accessed under Linux, and the ISO 9660 filesystem used by CD-ROMs.

Command | Action
debugfs | Debug ext2 filesystem.
dosfsck | Check and repair a DOS or VFAT filesystem.
dump | Back up data from a 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.
edquota | Edit filesystem quotas with vim.
fdformat | Format floppy disk.
fsck | Another name for e2fsck.
fsck.ext2 | Check and repair an ext2 filesystem.
mke2fs | Make a new ext2 filesystem.
mkfs | Make a new filesystem.
mkfs.ext2 | Another name for mke2fs.
mkfs.ext3 | Yet another name for mke2fs.
mklost+found | Make lost+found directory.
mkraid | Set up a RAID device.
mkswap | Designate swapspace.
mount | Mount a filesystem.
quotacheck | Audit stored quota information.
quotaon | Enforce quotas.
quotaoff | Do not enforce quotas.
quotastats | Display kernel quota statistics.
raidstart | Activate a RAID device.
raidstop | Turn off a RAID device.
rdev | Describe or change values for root filesystem.
repquota | Display quota summary.
resize2fs | Enlarge or shrink an ext2 filesystem.
restore | Restore data from a dump to a filesystem.
rootflags | List or set flags to use in mounting root filesystem.
setquota | Edit filesystem quotas.
showmount | List exported directories on a remote host.
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.
warnquota | Mail disk usage warnings to users.

2.1.8. Managing the Kernel

Command | Action
depmod | Create module dependency listing.
lsmod | List kernel modules.
modinfo | Print kernel module information.
modprobe | Load and remove a module and its dependent modules.
sysctl | Examine or modify kernel parameters at runtime.

2.1.9. Networking

Command | Action
ifconfig | Manage network interfaces.
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.
rndc | Send commands to a BIND nameserver.
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.
wvdial | Establish dial-up IP connections.

2.1.10. Printing

Command | Action
accept | Tell printer daemon to accept jobs.
lpadmin | Configure printer and class queues.
lpinfo | Show available printers and drivers.
lpmove | Move a print job to a different queue.
reject | Tell printer daemon to reject jobs.
tunelp | Tune the printer parameters.

2.1.11. Security and System Integrity

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

2.1.12. Starting and Stopping the System

Command | Action
chkconfig | Manage which services run in a runlevel.
ctrlaltdel | Shut down, then soft reboot system.
halt | Stop or shut down system.
init | Change runlevel.
reboot | Shut down, then hard 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, pidof, ps, and who.

Command | Action
fuser | Identify processes using file or filesystem.
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

Command | Action
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

Command | Action
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.


Section 2.2. Overview of Networking

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), cupsd (which sends documents to a printer, possibly over a network), and ftpd (which allows connections via ftp).

Most Unix networking commands are based on Internet protocols, 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 in addition to 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 NISwhich allow for transparent file and information sharing across networksand sendmail.

2.2.1. TCP/IP Administration

Command | Action
dig | Query domain nameservers.
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.
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.
tcpdump | Write network packet information to screen or file.
telnetd | Server for Telnet sessions from remote hosts.
tftpd | Server for restricted set of file transfers.

2.2.2. NFS and NIS Administration

Command | Action
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.


Section 2.3. Overview of TCP/IP

2.3. Overview of TCP/IP

TCP/IP is a suite of communications protocols that define how different types of computers talk to one another. It's named for its foundational protocols, the Transmission Control Protocol and the Internet Protocol. The Internet Protocol provides logical addressing as data moves between hosts: it splits data into packets, which are then forwarded to machines via the network. The Transmission Control Protocol ensures that the packets in a message are reassembled in the correct order at their final destination and that any missing datagrams are re-sent until they are correctly received. Other protocols provided as part of TCP/IP include:

Address Resolution Protocol (ARP)

Translates between Internet and local hardware addresses (Ethernet, etc.).

Internet Control Message Protocol (ICMP)

Error-message and control protocol.

Point-to-Point Protocol (PPP)

Enables TCP/IP (and other protocols) to be carried across both synchronous and asynchronous point-to-point serial links.

Reverse Address Resolution Protocol (RARP)

Translates between local hardware and Internet addresses (opposite of ARP).

Simple Mail Transport Protocol (SMTP)

Used by sendmail to send mail via TCP/IP.

Simple Network Management Protocol (SNMP)

Performs distributed network management functions via TCP/IP.

User Datagram Protocol (UDP)

Transfers data without first making a persistent connection between two systems the way TCP does. Sometimes called unreliable transport.

TCP/IP is covered in depth in the three-volume set Internetworking with TCP/IP (Prentice Hall). The commands in this chapter and the next are described in more detail in TCP/IP Network Administration and Linux Network Administrator's Guide, both published by O'Reilly.

In the architecture of TCP/IP protocols, data is passed down the stack (toward the Network Access Layer) when it is sent to the network, and up the stack when it is received from the network (see Figure 2-1).

2.3.1. IP Addresses

The IP (Internet protocol) address is a binary number that differentiates your machine from all others on the network. Each machine on the Internet must have

Figure 2-1. Layers in the TCP/IP protocol architecture

a unique IP address. The most common form of IP address used currently (IPv4) uses a 32-bit binary address. An IPv4 address contains two parts: a network part and a host part. The number of address bits used to identify the network and host differ according to the class of the address. There are three main address classes: A, B, and C (see Figure 2-2). The leftmost bits indicate what class each address is.

Figure 2-2. IP address structure

A standard called Classless Inter-Domain Routing (CIDR, or supernetting) extends the class system's idea of using initial bits to identify where packets should be routed. Under CIDR, a new domain can be created with any number of fixed leftmost bits (not just a multiple of eight). A CIDR address looks like a regular IPv4 address followed by a slash and a number indicating the number of network bits. For example: 192.168.32.1/24 or 128.66.128.1/17. Virtually all Internet gateway hosts now use CIDR.

IPv6, a newer standard, changes the method of addressing and increases the number of fields. An IPv6 address is 128 bits. Part of an IPv6 address is based on the Media Access Control (MAC) address of the network interface. The MAC address is unique for each network interface. When written, it is usually divided into eight 16-bit hexadecimal blocks separated by colons. For example:

    FE80:0000:0000:0000:0202:B3FF:FE1E:8329

To shorten this, leading zeros may be skipped, and any one set of consecutive zeros can be replaced with double colons. For example, the above address can be reduced to:

    FE80::202:B3FF:FE1E:8329

When IPv4 and IPv6 networks are mixed, the IPv4 address can be packed into the lower four bytes, yielding an address like 0:0:0:0:0:0:192.168.1.2, or ::192.168.1.2, or even ::C0A8:102.

Because improvements in IPv4, including CIDR, have relieved much of the pressure to migrate to IPv6, organizations have been slow to adopt IPv6. Some use it experimentally, but communication between organizations using IPv6 internally is still usually encapsulated inside IPv4 datagrams, and it will be a while before IPv6 becomes common.

If you wish to connect to the Internet, contact an Internet Service Provider (ISP). For most users, an ISP dynamically assigns an IP address to their systems. If you wish to always have the same address, have them assign you a static network address or range of addresses. If you are not connecting to an outside network, you can choose your own network address as long as it conforms to the IP address syntax. You should use the special reserved addresses provided in RFC 1597, which lists IP network numbers for private networks that don't have to be registered with the IANA (Internet Assigned Numbers Authority). An IP address is different from an Ethernet address, which is assigned by the manufacturer of the physical Ethernet card.

2.3.2. Gateways and Routing

Gateways are hosts responsible for exchanging routing information and forwarding data from one network to another. Each portion of a network that is under a separate local administration is called an autonomous system (AS). Autonomous systems connect to each other via exterior gateways. An AS also may contain its own system of networks, linked via interior gateways.

2.3.2.1 Gateway protocols

Gateway protocols include:

EGP (Exterior Gateway Protocol)

BGP (Border Gateway Protocol)

Protocols for exterior gateways to exchange information

RIP (Routing Information Protocol)

Interior gateway protocol; most popular for LANs

Hello Protocol

OSPF (Open Shortest Path First)

Interior gateway protocols

2.3.2.2 Routing daemons

While most networks will use a dedicated router as a gateway, GNU Zebra and routed, the routing daemons, can be run on a host to make it function as a gateway. Only one of them can run on a host at any given time. Zebra is the gateway routing daemon that replaces the older gated routing daemon. It allows a host to function as both an exterior and interior gateway and simplifies the routing configuration by combining the protocols RIP, Hello, BGP, EGP, and OSPF into a single package. We do not cover GNU Zebra in this book.

routed, a network routing daemon that uses RIP, allows a host to function only as an interior gateway, and manages the Internet routing tables. For more details on routed, see Chapter 3.

2.3.2.3 Routing tables

Routing tables provide information needed to route packets to their destinations. This information includes destination network, gateway to use, route status, and number of packets transmitted. Routing tables can be displayed with the netstat command.

2.3.3. Name Service

Each host on a network has a name that points to information about that host. Hostnames can be assigned to any device that has an IP address. A name service translates the hostnames (which are easy for people to remember) to IP addresses (the numbers the computer deals with).

2.3.3.1 DNS and BIND

The Domain Name System (DNS) is a distributed database of information about hosts on a network. Its structure is similar to that of the Unix filesysteman inverted tree, with the root at the top. The branches of the tree are called domains (or subdomains) and correspond to IP addresses. The most popular implementation of DNS is the BIND (Berkeley Internet Name Domain) software.

DNS works as a client/server application. The resolver is the client, the software that asks questions about host information. The nameserver is the process that answers the questions. The server side of BIND is the named daemon. You can interactively query nameservers for host information with the dig and host commands. See Chapter 3 for more details on named, dig, and host.

The nameserver of a domain is responsible for keeping (and providing on request) the names of the machines in its domain. Other nameservers on the network forward requests for these machines to this nameserver.

2.3.3.2 Domain names

The full domain name is the sequence of names from the current domain back to the root, with a period separating the names. For instance, oreilly.com indicates the domain oreilly (for O'Reilly Media, Inc.), which is under the domain com (for commercial). One machine under this domain is www.oreilly.com. Top-level domains include:

aero

Air-transport industry

biz

Commercial organizations

com

Commercial organizations

coop

Cooperatives

edu

United States educational organizations

gov

United States government organizations

info

Informative sites

int

International organizations

mil

United States military departments

museum

Museums

name

Names of individuals

net

Commercial Internet organizations, usually Internet service providers

org

Miscellaneous organizations

pro

Professionals, including accountants, lawyers, and physicians

Countries also have their own two-letter top-level domains based on two-letter country codes. For example, the Web server for the British Broadcasting System (BBC) in the United Kingdom has the following domain name: www.bbc.co.uk. Some domains (e.g., edu, gov, and mil) are sponsored by organizations that restrict their use; others (e.g., com, info, net, and org) are unrestricted. One special domain, arpa, is used for technical infrastructure purposes. The Internet Corporation for Assigned Names and Numbers (ICANN) oversees top-level domains and provides contact information for sponsored domains.

2.3.4. Configuring TCP/IP

Certain commands are normally run in the system's startup files to enable a system to connect to a network. These commands can also be run interactively.

2.3.4.1 ifconfig

The network interface represents the way that the networking software uses the hardware: the driver, the IP address, and so forth. To configure a network interface, use the ifconfig command. With ifconfig, you can assign an address to a network interface, setting the netmask, broadcast address, and IP address at boot time. You can also set network interface parameters, including the use of ARP, the use of driver-dependent debugging code, the use of one-packet mode, and the address of the correspondent on the other end of a point-to-point link. For more information on ifconfig, see Chapter 3.

2.3.4.2 Serial-line communication

There are two protocols for serial-line communication: Serial Line IP (SLIP) and Point-to-Point Protocol (PPP). These protocols let computers transfer information using the serial port instead of a network card, and a serial cable instead of an Ethernet cable. SLIP is rarely used anymore, having been replaced by PPP.

PPP was intended to remedy some of SLIP's failings; it can hold packets from non-Internet protocols, it implements client authorization and error detection/correction, and it dynamically configures each network protocol that passes through it. Under Linux, PPP exists as a driver in the kernel and as the daemon pppd. For more information on pppd, see Chapter 3.

2.3.5. Troubleshooting TCP/IP

The following commands can be used to troubleshoot TCP/IP. For more details on these commands, see Chapter 3:

dig

Query the DNS name service.

ifconfig

Provide information about the basic configuration of the network interface.

ifup and ifdown

On many systems used to start or stop a network interface.

iwconfig, iwlist, and wlancfg

Tools commonly used to configure a wireless network interface.

netstat

Display network status.

ping

Indicate whether a remote host can be reached.

route

Allows you to read and set default gateway information, as well as static routes.

tcpdump

Dump network packet information to the screen or to file.

traceroute

Trace route taken by packets to reach network host.


Section 2.4. Overview of Firewalls and Masquerading

2.4. Overview of Firewalls and Masquerading

A firewall is a secure computer that sits between an internal network and an external network (i.e., the Internet). It is configured with a set of rules that it uses to determine what traffic is allowed to pass and what traffic is barred. While a firewall is generally intended to protect the network from malicious or even accidentally harmful traffic from the outside, it can also be configured to monitor traffic leaving the network. As the sole entry point into the system, the firewall makes it easier to construct defenses and monitor activity.

The firewall can also be set up to present a single IP address to the outside world, even though multiple IP addresses may be used internally. This is known as masquerading. Masquerading can act as additional protection, hiding the very existence of a network. It also saves the trouble and expense of obtaining multiple IP addresses.

IP firewalling and masquerading are implemented with netfilter, also known as iptables. Earlier Linux kernels used ipchains or ipfwadm, which will not be covered here. Unlike the older tools, the facilities provided by netfilter are designed to be extensible; if there is some function missing from the implementation, you can add it.

The packet filtering facilities provide built-in rule sets. Each network packet is checked against each rule in the rule set until the packet either matches a rule or is not matched by any rule. These sets of rules are called chains. These chains are organized into tables that separate filtering functions from masquerading and packet mangling functions. If a match is found, the counters on that rule are incremented and any target for that rule is applied. A target might accept, reject, or masquerade a packet, or even pass it along to another chain for processing. Details on the chains provided in iptables can be found in Chapter 3.

In addition to these chains, you can create your own user-defined chains. You might want a special chain for your PPP interfaces or for packets from a particular site. To call a user-defined chain, you just make it the target for a match.

It is possible to make it through a chain without matching any rules that have a target. If no rule matches the packet in a user-defined chain, control returns to the chain from which it was called, and the next rule in that chain is checked. If no rule matches the packet in a built-in chain, a default policy for that chain is used. The default policy can be any of the special targets that determine what is done with a packet. The valid targets are detailed in Chapter 3.

You use the iptables command to define the rules. Once you have the rules defined you can use iptables-save to create a file with all the rule definitions, and iptables-restore to restore those definitions when you reboot.

For more information on the kinds of decisions you need to make and the considerations that go into defining the rules, see a general book on firewalls such as Building Internet Firewalls (O'Reilly). For more details on iptables, consult the Linux Network Administrator's Guide (O'Reilly), Linux iptables Pocket Reference (O'Reilly), or one of the relevant HOWTOs, such as the "Packet Filtering HOWTO." These HOWTOs and a number of tutorials are available on the Netfilter web site at http://www.netfilter.org/.


Section 2.5. Overview of NFS

2.5. Overview of NFS

The Network File System (NFS) is a distributed filesystem that allows users to mount remote filesystems as if they were local. NFS uses a client/server model in which a server exports directories to be shared and clients mount the directories to access the files in them. NFS eliminates the need to keep copies of files on several machines by letting the clients all share a single copy of a file on the server. NFS is an RPC-based application-level protocol. For more information on the architecture of network protocols, See Overview of TCP/IP.," earlier in this chapter.

2.5.1. Administering NFS

To set up NFS clients and servers, you must start the NFS daemons on the servers, export filesystems from the NFS servers, and mount the filesystems on the clients. The /etc/exports file is the NFS server configuration file; it controls which files and directories are exported and which kinds of access are allowed. Names and addresses for clients that should be allowed or denied access to NFS are kept in the /etc/hosts.allow and /etc/hosts.deny files.

2.5.2. Daemons

NFS server daemons, called nfsd daemons, run on the server and accept RPC calls from clients. NFS servers also run the mountd daemon to handle mount requests. On the client, caching and buffering are handled by biod, the block I/O daemon. The portmap daemon maps RPC program numbers to the appropriate TCP/IP port numbers. If the portmap daemon is not running properly, NFS will not work either.

2.5.3. Exporting Filesystems

To set up an NFS server, first check that all the hosts that will mount your filesystem can reach your host. Next, edit the /etc/exports file on the server. Each entry in this file indicates the name of a directory to be exported, domain names of machines that will have access to that particular mount point, and any options specific to that machine. A typical entry looks like:

    /projects hostname1(rw) hostname2(ro)

If you are running mountd, the files will be exported as allowed by the permissions in /etc/exports. See the exports manpage for all available export options.

2.5.4. Mounting Filesystems

To enable an NFS client, mount a remote filesystem after NFS is started, either by using the mount command or by specifying default remote filesystems in /etc/fstab. For example:

    # mount servername:/projects /mnt/nfs/projects

A mount request calls the server's mountd daemon, which checks the access permissions of the client and returns a pointer to a filesystem. Once a directory is mounted, it remains attached to the local filesystem until it is unmounted with the umount command or until the local system is rebooted.

Usually, only a privileged user can mount filesystems with NFS. However, you can enable users to mount and unmount selected filesystems using the mount and unmount commands if the user option is set in /etc/fstab. This can reduce traffic by having filesystems mounted only when needed. To enable user mounting, create an entry in /etc/fstab for each filesystem to be mounted. You can verify filesystems that have been mounted by using the mount or showmount commands. Or, you can read the contents of the /etc/mtab file.


Section 2.6. Overview of NIS

2.6. Overview of NIS

The Network Information System (NIS) refers to the service formerly known as Sun Yellow Pages (YP). It is used to make configuration information consistent on all machines in a network. It does this by designating a single host as the master of all the system administration files and databases and distributing this information to all other hosts on the network. The information is compiled into databases called maps. NIS is built on the RPC protocol.

Another version of NIS, NIS+, adds encryption and strong authentication to NIS. NIS+ is a proprietary standard created by Sun Microsystems. This chapter discusses standard NIS, which is supported by most Linux systems. There are currently two NIS servers freely available for Linux, yps and ypserv. We describe ypserv in this book.

2.6.1. Servers

In NIS, there are two types of servers: master servers and slave servers. Master servers are responsible for maintaining the maps and distributing them to the slave servers. The files are then available locally to requesting processes.

2.6.2. Domains

An NIS domain is a group of hosts that use the same set of maps. The maps are contained in a subdirectory of /var/yp having the same name as the domain. The machines in a domain share password, host, and group file information. NIS domain names are set with the domainname command.

2.6.3. NIS Maps

NIS stores information in database files called maps. Each map consists of a pair of dbm database files, one containing a directory of keys (a bitmap of indices) and the other containing data values. The non-ASCII structure of dbm files necessitates using NIS tools such as yppush to move maps between machines.

The file /var/yp/YP_MAP_X_LATE contains a complete listing of active NIS maps, as well as NIS aliases for NIS maps. All maps must be listed in this file in order for NIS to serve them.

2.6.4. Map Manipulation Utilities

The following utilities are used to administer NIS maps:

makedbm

Make dbm files. Modify only ypserv's map and any nondefault maps.

ypinit

Build and install NIS databases. Manipulate maps when NIS is being initialized. Should not be used when NIS is already running.

yppush

Transfer updated maps from the master server.


Section 2.7. Administering NIS

2.7. Administering NIS

NIS is enabled by setting up NIS servers and NIS clients. The descriptions given here describe NIS setup using ypserv, which does not support a master/slave server configuration. All NIS commands depend on the RPC portmap program, so make sure it is installed and running before setting up NIS.

2.7.1. Setting Up an NIS Server

Setting up an NIS server involves the following steps:

  1. Set a domain name for NIS using domainname.

  2. Edit the ypMakefile, which identifies which databases to build and what sources to use in building them.

  3. Copy the ypMakefile to /var/yp/Makefile.

  4. Run make from the /var/yp directory, which builds the databases and initializes the server.

  5. Start ypserv, the NIS server daemon.

2.7.2. Setting Up an NIS Client

Setting up an NIS client involves only the following steps:

  1. Set the domain name for NIS using domainname, which should be the same name used by the NIS server.

  2. Run ypbind.

2.7.3. NIS User Accounts

NIS networks have two kinds of user accounts: distributed and local. Distributed accounts must be administered from the master machine; they provide information that is uniform on each machine in an NIS domain. Changes made to distributed accounts are distributed via NIS maps. Local accounts are administered from the local computer; they provide account information unique to a specific machine. They are not affected by NIS maps, and changes made to local accounts do not affect NIS. When NIS is installed, preexisting accounts default to local accounts.


Section 2.8. RPC and XDR

2.8. RPC and XDR

RPC (Remote Procedure Call) is the session protocol used by both NFS and NIS. It allows a host to make a procedure call that appears to be local but is really executed remotely on another machine on the network. RPC is implemented as a library of procedures, plus a network standard for ordering bytes and data structures called XDR (eXternal Data Representation).


Chapter 3. Linux Commands

This chapter presents Linux's user, programmer, and system administration commands. These are entered into a shell at the console or on a virtual terminal on a graphical desktop.

Each entry is labeled with the command name on the outer edge of the page. The syntax line is followed by a brief description and a list of available options. Many commands come with examples at the end of the entry. If you need only a quick reminder or suggestion about a command, you can skip directly to the examples.

Typographic conventions for describing command syntax are listed in the Preface. For help in locating commands, see the index at the back of this book.

We've tried to be as thorough as possible in listing options. The basic command information and most options should be correct; however, there are many Linux distributions and many versions of commands. New options are added, and sometimes old options are dropped. You may, therefore, find some differences between the options you find described here and the ones on your system. When there seems to be a discrepancy, check the manpage. For most commands, you can also use the option --help to get a brief usage message. (Even when it isn't a valid option, it will usually result in an "invalid option" error along with the usage message.)

Traditionally, commands take single-letter options preceded by a single hyphen, such as -d. A more recent convention allows long options preceded by two hyphens, such as --debug. Often, a feature can be invoked through either the old style or the new style of options.


Chapter 4. Boot Methods

This chapter describes some techniques for booting your Linux system. Depending on your hardware and whether you want to run any other operating systems, you can configure the system to boot Linux automatically or to provide a choice between several operating systems. Choosing between operating systems is generally referred to as dual booting, although you can actually boot more than two.

Once your Linux system is installed, rebooting the system is generally straightforward. But with the wide variety of hardware and software in use, there are many possibilities for configuring your boot process. The most common choices are:

  • Boot Linux from a floppy or bootable CD, leaving any other operating system to boot from the hard drive.

  • Use the Linux Loader, LILO.[*] This is the traditional method of booting and lets you boot both Linux and other operating systems.

    [*] LILO is a boot program for i386-architecture machines. On the Alpha, the equivalent boot program is called MILO (Mini Loader), and on the SPARC, it's called SILO.

  • Use the Grand Unified Bootloader (GRUB), the GNU graphical boot loader and command shell. Like LILO, GRUB lets you boot both Linux and other operating systems. For now, GRUB runs only on i386-based systems.

  • Run Loadlin, which is an MS-DOS program that boots Linux from within DOS.

Other boot managers that can load Linux are available, but we don't discuss them here. We also won't talk further about booting from a floppy or CD or via Loadlin, except to say that whatever method you choose for booting, be sure to have a working boot disk available for emergency use. In particular, don't experiment with the files and options in this chapter unless you have a boot disk, because any error could leave you unable to boot from the hard disk. Note, though, that one of the advantages of using GRUB is that if there is a problem booting from the menu, it drops you down to the command-line interface so you can enter commands directly and try to recover. Also, see Creating a GRUB boot floppy.," later in this chapter, for information on making a GRUB boot floppy.[*]

[*] Unfortunately, there is no standard set of instructions we can provide for making a bootable CD. Your best bet is to use a bootable installation CD for your distribution. Also, instructions and utilities are available online for making bootable CDs.


Section 4.1. The Boot Process

4.1. The Boot Process

On an x86-based PC, the first sector of every hard disk is known as the boot sector and contains the partition table for that disk and possibly also code for booting an operating system. The boot sector of the first hard disk is known as the master boot record (MBR), because when you boot the system, the BIOS transfers control to a program that lives on that sector along with the partition table. That code is the boot loader, the code that initiates an operating system. When you add Linux to the system, you need to modify the boot loader, replace it, or boot from a floppy or CD to start Linux.

In Linux, each disk and each partition on the disk is treated as a device. For example, the entire first hard disk is known as /dev/hda, and the entire second hard disk is /dev/hdb. The first partition of the first hard drive is /dev/hda1, and the second partition is /dev/hda2. The first partition of the second hard drive is /dev/hdb1, and so on. If your drives are SCSI instead of IDE, the naming works the same way, except that the devices are /dev/sda, /dev/sda1, and so on. Thus, if you want to specify that the Linux partition is the second partition of the first hard drive (as in the examples in this chapter), you refer to it as /dev/hda2. Note, though, that GRUB has its own disk naming convention, described later in this chapter in GRUB: The Grand Unified Bootloader.."

Once you've made the decision to install LILO or GRUB, you still need to decide how it should be configured. If you want your system to dual-boot Linux and Windows 95/98/ME, you can install LILO or GRUB on the MBR and set it up to let you select the system to boot. Dual-booting Linux and Windows NT/2000/XP is not quite as straightforward because these systems use the Windows NT loader, which is installed on the MBR and expects to be in charge. The standard solution described in this chapter is to add Linux as an option in the NT loader and install LILO or GRUB in the Linux partition as a secondary boot loader. The result is that the NT loader transfers control to the secondary loader, which then boots Linux. See Dual-Booting Linux and Windows NT/2000/XP.," later in this chapter, for more information. You can also install one of the Linux boot loaders in the MBR and use it to boot Windows. (See the "Linux+WindowsNT" and the "Multiboot with GRUB" mini-HOWTOs if you're interested in doing that.)

When you install the boot loader (either LILO or GRUB) on the MBR, it replaces the MS-DOS boot loader or any other boot loader that may be there, such as the Windows NT loader. If you have problems with your installation or you simply want to restore the original boot loader, you can do one of the following:

  • If you're running LILO, you can boot Linux from a floppy or CD and restore the boot sector, which LILO automatically backs up:

        $ /sbin/lilo -u

  • If you have the capability, boot to DOS and run the fdisk command with a special option that rebuilds the MBR:

        C:> fdisk /mbr

  • For Windows 2000 and Windows XP, which do not have an fdisk command, boot your computer from the Windows CD (or the Windows boot floppies if you can't boot from your CD drive). When you see "Welcome to Setup," press R (for repair) and, in Windows 2000, then press C. Select your Windows installation from the numbered list that is displayed (there may be only one entry) and enter the administrator password at the prompt. Enter the command fixmbr at the command-line prompt and confirm it with y. After the MBR has been restored, type exit to reboot.

The common element in all three methods is that they replace the boot loader on the MBR with the original Microsoft boot loader. The boot loader on the MBR is the one that will be used to boot the system. This means that if you want to switch from LILO to GRUB, say, or from GRUB to LILO, you don't need to uninstall the old loader; simply install the new one.

The rest of this chapter describes the various techniques for booting Linux and the options that you can specify to configure both the boot loader and the Linux kernel. Whether you use LILO or GRUB, you can pass options to the loader and specify options for the kernel.


Section 4.2. LILO: The Linux Loader

4.2. LILO: The Linux Loader

In addition to booting Linux, LILO can boot other operating systems, such as MS-DOS, Windows 95/98/ME, or any of the BSD systems. During installation, the major Linux distributions provide the opportunity to install LILO; it can also be installed later if necessary. LILO can be installed on the MBR of your hard drive or as a secondary boot loader on the Linux partition. LILO consists of several pieces, including the boot loader itself, a configuration file (/etc/lilo.conf), a map file (/boot/map) containing the location of the kernel, and the lilo command (/sbin/lilo), which reads the configuration file and uses the information to create or update the map file and to install the files LILO needs.

One thing to remember about LILO is that it has two aspects: the boot loader and the lilo command. The lilo command configures and installs the boot loader and updates it as necessary. The boot loader is the code that executes at system boot time and boots Linux or another operating system.

4.2.1. The LILO Configuration File

The lilo command reads the LILO configuration file, /etc/lilo.conf, to get the information it needs to install LILO. Among other things, it builds a map file containing the locations of all disk sectors needed for booting.

Note that any time you change /etc/lilo.conf or rebuild or move a kernel image, you need to rerun lilo to rebuild the map file and update LILO.

The configuration file starts with a section of global options, described in the next section. Global options are those that apply to every system boot, regardless of the operating system you are booting. Here is an example of a global section (a hash sign, #, begins a comment):

    boot=/dev/hda           # The boot device is /dev/hda
    map=/boot/map           # Save the map file as /boot/map
    install=/boot/boot.b    # The file to install as the new boot sector
    prompt                  # Always display the boot prompt
    timeout=30              # Set a 3-second (30 tenths of a second) timeout

Following the global section, there is one section of options for each Linux kernel and for each non-Linux operating system that you want LILO to be able to boot. Each of these sections is referred to as an image section because each boots a different kernel image (shorthand for a binary file containing a kernel) or another operating system. Each Linux image section begins with an image= line.

    image=/boot/vmlinuz     # Linux image file
       label=linux          # Label that appears at the boot prompt
       root=/dev/hda2       # Location of the root filesystem
       vga=ask              # Always prompt the user for VGA mode
       read-only            # Mount read-only to run fsck for a filesystem check

The equivalent section for a non-Linux operating system begins with other= instead of image=. For example:

    other=/dev/hda1         # Location of the partition
       label=win98
       table=/dev/hda       # Location of the partition table

Put LILO configuration options that apply to all images into the global section of /etc/lilo.conf, and options that apply to a particular image into the section for that image. If an option is specified in both the global section and an image section, the setting in the image section overrides the global setting for that image.

Here is an example of a complete /etc/lilo.conf file for a system that has the Linux partition on /dev/hda2:

    ## Global section
    boot=/dev/hda2
    map=/boot/map
    delay=30
    timeout=50
    prompt
    vga=ask

    ## Image section: For regular Linux
    image=/boot/vmlinuz
      label=linux
      root=/dev/hda2
      install=/boot/boot.b
      map=/boot/map
      read-only

    ## Image section: For testing a new Linux kernel
    image=/testvmlinuz
      label=testlinux
      root=/dev/hda2
      install=/boot/boot.b
      map=/boot/map
      read-only
      optional               # Omit image if not available when map is built

    ## Image section: For booting DOS
    other=/dev/hda1
      label=dos
      loader=/boot/chain.b
      table=/dev/hda         # The current partition table

    ## Image section: For booting Windows 98
    other=/dev/hda1
      label=win98
      loader=/boot/chain.b
      table=/dev/hda

4.2.1.1 Global options

In addition to the options listed here, the kernel options append, read-only, read-write, root, and vga (described later in Kernel options.) can also be set as global options.

backup=backup-file

Copy the original boot sector to backup-file instead of to /boot/boot.nnnn, where nnnn is a number that depends on the disk device type.

boot=boot-device

Set the name of the device that contains the boot sector. boot defaults to the device currently mounted as root, such as /dev/hda2. Specifying a device such as /dev/hda (without a number) indicates that LILO should be installed in the master boot record; the alternative is to set it up on a particular partition, such as /dev/hda2.

change-rules

Begin a section that redefines partition types at boot time for hiding and unhiding partitions. See the LILO User's Guide, which comes with the LILO distribution, for detailed information on using this option and creating a new rule set.

compact

Merge read requests for adjacent disk sectors to speed up booting. Use of compact is particularly recommended when booting from a floppy disk. Use of compact may conflict with linear.

default=name

Use the image name as the default boot image. If default is omitted, the first image specified in the configuration file is used.

delay=tsecs

Specify, in tenths of a second, how long the boot loader should wait before booting the default image. If serial is set, delay is set to a minimum of 20. The default is not to wait. See Boot-Time Kernel Options. " at the end of this chapter for ways to get the boot prompt if no delay is set.

disk=device-name

Define parameters for the disk specified by device-name if LILO can't figure them out. Normally, LILO can determine the disk parameters itself, and this option isn't needed. When disk is specified, it is followed by one or more parameter lines, such as:

    disk=/dev/sda
      bios=0x80      # First disk is usually 0x80, second is usually 0x81
      sectors=...
      heads=...

Note that this option is not the same as the disk geometry parameters you can specify with the hd boot command-line option. With disk, the information is given to LILO; with hd, it is passed to the kernel. Note also that if either heads or sectors is specified, they must both be specified. The parameters that can be specified with disk are listed briefly here; they are described in detail in the LILO User's Guide.

bios=bios-device-code

The number the BIOS uses to refer to the device. See the previous example.

cylinders=cylinders

The number of cylinders on the disk.

heads=heads

The number of heads on the disk.

inaccessible

Tell LILO that the BIOS can't read the disk; used to prevent the system from becoming unbootable if LILO thinks the BIOS can read it. If this parameter is specified, it must be the only parameter.

partition=partition-device

Start a new section for a partition. The section contains one variable, start=partition-offset, which specifies the zero-based number of the first sector of the partition:

    partition=/dev/sda1
      start=2048

sectors=sectors

The number of sectors per track.

disktab=disktab-file

This option has been superseded by the disk= option.

fix-table

If set, allow lilo to adjust 3-D addresses (addresses specified as sector/head/cylinder) in partition tables. This is sometimes necessary if a partition isn't track-aligned and another operating system such as MS-DOS is on the same disk. See the lilo.conf manpage for details.

force-backup=backup-file

Like backup, but overwrite an old backup copy if one exists.

ignore-table

Tell lilo to ignore corrupt partition tables.

install=boot-sector

Install the specified file as the new boot sector. If install is omitted, the boot sector defaults to /boot/boot.b.

lba32

Generate 32-bit Logical Block Addresses instead of sector/head/cylinder addresses, allowing booting from any partition on hard disks greater than 8.4 GB (i.e., remove the 1024-cylinder limit). Requires BIOS support for the EDD packet call interface[*] and at least LILO Version 21-4.

[*] If your BIOS is dated after 1998, it should include EDD packet call interface support.

linear

Generate linear sector addresses, which do not depend on disk geometry, instead of 3-D (sector/head/cylinder) addresses. If LILO can't determine your disk's geometry itself, you can try using linear; if that doesn't work, then you need to specify the geometry with disk=. Note, however, that linear sometimes doesn't work with floppy disks, and it may conflict with compact.

lock

Tell LILO to record the boot command line and use it as the default for future boots until it is overridden by a new boot command line. lock is useful if there are kernel options that you need to enter on the boot command line every time you boot the system.

map=map-file

Specify the location of the map file. Defaults to /boot/map. The map file records the location of the kernel(s) used on the system.

message=message-file

Specify a file containing a message to be displayed before the boot prompt. The message can include a formfeed character (Ctrl-L) to clear the screen. The map file must be rebuilt by rerunning the lilo command if the message file is changed or moved. The maximum length of the file is 65,535 bytes.

nowarn

Disable warning messages.

optional

Specify that any image that is not available when the map is created should be omitted and not offered as an option at the boot prompt. Like the per-image option optional, but applies to all images.

password=password

Specify a password that the user is prompted to enter when trying to load an image. The password is not encrypted in the configuration file, so if passwords are used, permissions should be set so that only the superuser is able to read the file. This option is like the per-image version, except that all images are password-protected and they all have the same password.

prompt

Automatically display the boot prompt without waiting for the user to press the Shift, Alt, or Scroll Lock key. Note that setting prompt without also setting timeout prevents unattended reboots.

restricted

Can be used with password to indicate that a password needs to be entered only if the user specifies parameters on the command line. Like the per-image restricted option, but applies to all images.

serial=parameters

Allow the boot loader to accept input from a serial line as well as from the keyboard. Sending a break on the serial line corresponds to pressing a Shift key on the console to get the boot loader's attention. All boot images should be password-protected if serial access is insecure (e.g., if the line is connected to a modem). Setting serial automatically raises the value of delay to 20 (i.e., two seconds) if it is less than that. The parameter string parameters has the following syntax:

    port[,bps[parity[bits]]]

For example, to initialize COM1 with the default parameters:

    serial=0,2400n8

The parameters are:

port

The port number of the serial port. The default is 0, which corresponds to COM1 (/dev/ttys0). The value can be one of 0 through 3, for the four possible COM ports.

bps

The baud rate of the serial port. Possible values of bps are 110, 300, 1200, 2400, 4800, 9600, 19200, and 38400. The default is 2400 bps.

parity

The parity used on the serial line. Parity is specified as n or N for no parity, e or E for even parity, and o or O for odd parity. However, the boot loader ignores input parity and strips the 8th bit.

bits

Specify whether a character contains 7 or 8 bits. Default is 8 with no parity and 7 otherwise.

timeout=tsecs

Set a timeout (specified in tenths of a second) for keyboard input. If no key has been pressed after the specified time, the default image is booted automatically. timeout is also used to determine when to stop waiting for password input. The default timeout is infinite.

verbose=level

Turn on verbose output, where higher values of level produce more output. If -v is also specified on the lilo command line, the level is incremented by 1 for each occurrence of -v. The maximum verbosity level is 5.

4.2.1.2 Image options

The following options are specified in the image section for a particular boot image. The image can be a Linux kernel or a non-Linux operating system.

alias=name

Provide an alternate name for the image that can be used instead of the name specified with the label option.

image=pathname

Specify the file or device containing the boot image of a bootable Linux kernel. Each per-image section that specifies a bootable Linux kernel starts with an image option. See also the range option.

label=name

Specify the name that is used for the image at the boot prompt. Defaults to the filename of the image file (without the path).

loader=chainloader

For a non-Linux operating system, specify the chain loader to which LILO should pass control for booting that operating system. The default is /boot/chain.b. If the system will be booted from a drive that is neither the first hard disk or a floppy, the chainloader must be specified.

lock

Like lock, as described in the previous global options section; it can also be specified in an image section.

optional

Specify that the image should be omitted if it is not available when the map is created by the lilo command. Useful for specifying test kernels that are not always present.

other=pathname

Specify the path to a file that boots a non-Linux system. Each per-image section that specifies a bootable non-Linux system starts with an other option.

password=password

Specify that the image is password-protected and provide the password that the user is prompted for when booting. The password is not encrypted in the configuration file, so if passwords are used, only the superuser should be able to read the file.

range=sectors

Used with the image option, when the image is specified as a device (e.g., image=/dev/fd0), to indicate the range of sectors to be mapped into the map file. sectors can be given as the range start-end or as start+number, where start and end are zero-based sector numbers and number is the increment beyond start to include. If only start is specified, only that one sector is mapped. For example:

    image=/dev/fd0
    range=1+512   # take 512 sectors, starting with sector 1

restricted

Specify that a password is required for booting the image only if boot parameters are specified on the command line.

table=device

Specify, for a non-Linux operating system, the device that contains the partition table. If table is omitted, the boot loader does not pass partition information to the operating system being booted. Note that /sbin/lilo must be rerun if the partition table is modified. This option cannot be used with unsafe.

unsafe

Can be used in the per-image section for a non-Linux operating system to indicate that the boot sector should not be accessed when the map is created. If unsafe is specified, then some checking isn't done, but the option can be useful for running the lilo command without having to insert a floppy disk when the boot sector is on a fixed-format floppy disk device. This option cannot be used with table.

4.2.1.3 Kernel options

The following kernel options can be specified in /etc/lilo.conf as well as on the boot command line:

append=string

Append the options specified in string to the parameter line passed to the kernel. This typically is used to specify certain hardware parameters. For example, while BIOSes on newer systems can recognize more than 64 MB of memory, BIOSes on older systems are limited to 64 MB. If you are running Linux on such a system, you can use append:

    append="mem=128M"

initrd=filename

Specify the file to load into /dev/initrd when booting with a RAM disk. See also the options load_ramdisk (in Boot-Time Kernel Options.," later in this chapter) and prompt_ramdisk, ramdisk_size, and ramdisk_start in this section.

literal=string

Like append, but replace all other kernel boot options.

noinitrd

Preserve the contents of /dev/initrd so they can be read after the kernel is booted.

prompt_ramdisk=n

Specify whether the kernel should prompt you to insert the floppy disk that contains the RAM disk image, for use during Linux installation. Values of n are:

0 Don't prompt. Usually used for an installation in which the kernel and the RAM disk image both fit on one floppy.

1 Prompt. This is the default.

ramdisk_size=n

Specify the amount of memory, in kilobytes, to be allocated for the RAM disk. The default is 4096, which allocates 4 MB.

ramdisk_start=offset

Used for a Linux installation in which both the kernel and the RAM disk image are on the same floppy. offset indicates the offset on the floppy where the RAM disk image begins; it is specified in kilobytes.

read-only

Specify that the root filesystem should be mounted read-only for filesystem checking (fsck), after which it is typically remounted read/write.

read-write

Specify that the root filesystem should be mounted read/write.

root=root-device

Specify the device that should be mounted as root. If the special name current is used as the value, the root device is set to the device on which the root filesystem currently is mounted. Defaults to the root-device setting contained in the kernel image.

vga=mode

Specify the VGA text mode that should be selected when booting. The mode defaults to the VGA mode setting in the kernel image. The values are case-insensitive. They are:

ask

Prompt the user for the text mode. Pressing Enter in response to the prompt displays a list of the available modes.

extended (or ext)

Select 80x50 text mode.

normal

Select normal 80x25 text mode.

number

Use the text mode that corresponds to number. A list of available modes for your video card can be obtained by booting with vga=ask and pressing Enter.

4.2.2. The lilo Command

You need to run the lilo command to install the LILO boot loader and to update it whenever the kernel changes or to reflect changes to /etc/lilo.conf. Note that if you replace your kernel image without rerunning lilo, your system may be unable to boot your system.

The path to the lilo command is usually /sbin/lilo. The syntax of the command is:

    lilo [options]

Some of the options correspond to /etc/lilo.conf keywords:

Configuration keyword | Command option
boot=bootdev | -b bootdev
compact | -c
delay=tsecs | -d tsecs
default=label | -D label
disktab=file | -f file
install=bootsector | -i bootsector
lba32 | -L
linear | -l
map=mapfile | -m mapfile
fix-table | -P fix
ignore-table | -P ignore
backup=file | -s file
force-backup=file | -S file
verbose=level | -v

These options should be put in the configuration file whenever possible; putting them on the lilo command line instead of in /etc/lilo.conf is now deprecated. The next section describes those options that can be given only on the lilo command line; the others were described earlier.

4.2.3. lilo Command Options

The following list describes lilo command options that are available only on the command line. Multiple options are given separately; for example:

    $ lilo -q -v

-C config-file

Specify an alternative to the default configuration file (/etc/lilo.conf). lilo uses the configuration file to determine which files to map when it installs LILO.

-I label

Print the path to the kernel specified by label to standard output, or an error message if no matching label is found. For example:

    $ lilo -I linux
    /boot/vmlinuz-2.0.34-0.6

-q

List the currently mapped files. lilo maintains a file (/boot/map by default) containing the name and location of the kernel(s) to boot. Running lilo with this option prints the names of the files in the map file to standard output, as in this example (the asterisk indicates that linux is the default):

    $ lilo -q
    linux     *
    test

-r root-directory

Specify that before doing anything else, lilo should chroot to the indicated directory. Used for repairing a setup from a boot floppy; you can boot from a floppy but have lilo use the boot files from the hard drive. For example, if you issue the following commands, lilo will get the files it needs from the hard drive:

    $ mount /dev/hda2 /mnt
    $ lilo -r /mnt

-R command-line

Set the default command for the boot loader the next time it executes. The command executes once and then is removed by the boot loader. This option typically is used in reboot scripts, just before calling shutdown -r.

-t Indicate that this is a testdo not really write a new boot sector or map file. Can be used with -v to find out what lilo would do during a normal run.

-u device-name

Uninstall lilo by restoring the saved boot sector from /boot/boot.nnnn, after validating it against a timestamp. device-name is the name of the device on which LILO is installed, such as /dev/hda2.

-U device-name

Like -u, but do not check the timestamp.

-V

Print the lilo version number.


Section 4.3. GRUB: The Grand Unified Bootloader

4.3. GRUB: The Grand Unified Bootloader

Like LILO, the GRUB boot loader can load other operating systems in addition to Linux. GRUB has become the default bootloader for many flavors of Linux. It was written by Erich Boleyn to boot operating systems on PC-based hardware and is now developed and maintained by the GNU project. GRUB was intended to boot operating systems that conform to the Multiboot Specification, which was designed to create one booting method that would work on any conforming PC-based operating system. In addition to multiboot-conforming systems, GRUB can boot directly to Linux, FreeBSD, OpenBSD, and NetBSD. It can also boot other operating systems such as Microsoft Windows indirectly, through the use of a chainloader. The chainloader loads an intermediate file, and that file loads the operating system's boot loader.

GRUB provides a graphical menu interface. It also provides a command interface that is accessible both while the system is booting (the native command environment) and from the command line once Linux is running.

While LILO works perfectly well, especially if you usually boot the default image, GRUB has some advantages. The graphical menu interface shows you exactly what your choices are for booting, so you don't have to remember them. It also lets you easily edit an entry on the fly, or drop down into the command interface. In addition, if you are using the menu interface and something goes wrong, GRUB automatically puts you into the command interface so you can attempt to recover and boot manually. Another advantage of GRUB is that if you install a new kernel or update the configuration file, that's all you have to do; with LILO, you also have to remember to rerun the lilo command to reinstall the boot loader. On the other hand, if you are used to LILO, don't need to see the prompts often, and have a stable system, LILO is quick and convenient.

A GRUB installation consists of at least two and sometimes three executables, known as stages. The stages are:

Stage 1

Stage 1 is the piece of GRUB that resides in the MBR or the boot sector of another partition or drive. Since the main portion of GRUB is too large to fit into the 512 bytes of a boot sector, Stage 1 is used to transfer control to the next stage, either Stage 1.5 or Stage 2.

Stage 1.5

Stage 1.5 is loaded by Stage 1 only if the hardware requires it. Stage 1.5 is filesystem-specific; that is, there is a different version for each filesystem that GRUB can load. The name of the filesystem is part of the filename (e2fs_stage1_5, fat_stage1_5, etc.). Stage 1.5 loads Stage 2.

Stage 2

Stage 2 runs the main body of the GRUB code. It displays the menu, lets you select the operating system to be run, and starts the system you've chosen.

If it was compiled with netboot support, GRUB can also be used to boot over a network. We don't describe that process here; see the file netboot/README.netboot in the GRUB source directory for detailed information.

One of the first things to understand about GRUB is that it uses its own naming conventions. Drives are numbered starting from 0; thus, the first hard drive is hd0, the second hard drive is hd1, the first floppy drive is fd0, and so on. Partitions are also numbered from 0, and the entire name is put in parentheses. For example, the first partition of the first drive, /dev/hda1, is known as (hd0,0) to GRUB, and the third partition of the second drive is (hd1,2). GRUB makes no distinction between IDE drives and SCSI drives; thus the first drive is hd0 regardless of whether it is IDE or SCSI.

Files are specified either by the filename or by blocklist, which is used to specify files such as chainloaders that aren't part of a filesystem. A filename looks like a standard Unix path specification with the GRUB device name prepended; for example:

    (hd0,0)/grub/grub.conf

If the device name is omitted, the GRUB root device is assumed. The GRUB root device is the disk or partition where the kernel image is stored, set with the root command. See GRUB Commands.," later in the chapter, for the command descriptions.

When you use blocklist notation, you tell GRUB which blocks on the disk contain the file you want. Each section of a file is specified as the offset on the partition where the block begins plus the number of blocks in the section. The offset starts at 0 for the first block on the partition. The syntax for blocklist notation is:

    [device][offset]+length[,offset]+length...

In this case, too, the device name is optional for a file on the root device. With blocklist notation, you can also omit the offset if it is 0. A typical use of blocklist notation is when using a chainloader to boot Windows. If GRUB is installed in the MBR, you can chainload Windows by setting the root device to the partition that has the Windows boot loader, making it the active partition, and then using the chainloader command to read the Windows boot sector:

    rootnoverify (hd0,0)

    makeactive

    chainloader +1

In this example, the blocklist notation (+1) does not include either the device name or the offset because we set the root device to the Windows partition, and the Windows loader begins at offset 0 of that partition.

GRUB also includes a device map. The device map is an ASCII file, usually /boot/grub/device.map. Since the operating system isn't loaded yet when you use GRUB to boot Linux (or any other operating system), GRUB knows only the BIOS drive names. The purpose of the device map is to map the BIOS drives to Linux devices. For example:

    (fd0)   /dev/fd0

    (hd0)   /dev/hda

4.3.1. Installing GRUB

Installing GRUB involves two stages. First, you install the GRUB files on your system, either by compiling and installing the source tarball or from a package. That puts the GRUB files in the correct locations on your system. The second step is to install the GRUB software as your boot manager. This is the step we describe in this section.

If you installed GRUB as part of your Linux installation, the distribution's installation program took care of both stages of installing GRUB, and you'll most likely see the GRUB menu when you boot Linux. If you didn't install GRUB as part of your Linux installation, you have two choices. The easiest way to install GRUB is with the grub-install shell script that comes with GRUB. If grub-install doesn't work, or if you want to do the installation manually, you can run the grub command and issue the installation commands yourself.

The following sections describe how to create a GRUB boot floppy and how to install GRUB.

4.3.1.1 Creating a GRUB boot floppy

You can create a GRUB boot floppy for everyday use or to have for an emergency. The following instructions make a floppy that boots to the GRUB command line:

  1. From the directory where GRUB was installed (e.g., /usr/share/grub/i386-pc), use the dd command to write the file stage1 to the floppy:

        $ dd if=stage1 of=/dev/fd0 bs=512 count=1

    This command writes one block, with a block size of 512, from the input file stage1 to the floppy device /dev/fd0.

  2. Now write the file stage2 to the floppy, skipping over the first block (seek=1) so you don't overwrite stage1:

        $ dd if=stage2 of=/dev/fd0 bs=512 seek=1

Put together, the process looks like this

    $ dd if=stage1 of=/dev/fd0 bs=512 count=1
    1+0 records in
    1+0 records out
    $ dd if=stage2 of=/dev/fd0 bs=512 seek=1
    254+1 records in
    254+1 records out

The boot floppy is now ready to boot to the GRUB command line.

You can also make a boot floppy that boots to the GRUB menu:

  1. Create a GRUB configuration file (/boot/grub/grub.conf) if you don't already have one. The configuration file is described later in The GRUB Configuration File.."

  2. Create a filesystem on your floppy disk. For example:

        $ mke2fs /dev/fd0

  3. Mount the floppy drive and create the directory /boot/grub:

        $ mount /mnt
    $ mkdir /mnt/boot
    $ mkdir /mnt/boot/grub

  4. Copy the stage1, stage2, and grub.conf GRUB images from /boot/grub on your Linux partition to /mnt/boot/grub.

  5. Run the grub command. This example assumes the command is in /sbin/grub, but it might be in /usr/sbin/grub on your system:

        $ /sbin/grub --batch <<EOT
    root (fd0)
    setup (fd0)
    quit
    EOT

You should now be able to boot to the GRUB menu from the floppy disk you just created.

4.3.1.2 Using grub-install

GRUB comes with a shell script, grub-install, which uses the GRUB shell to automate the installation. The command syntax is:

    grub-install options install-device

where install-device is the name of the device on which you want to install GRUB, specified as either the GRUB device name (e.g., (hd0)) or the system device (e.g., /dev/hda). For example, you might issue the following command (as root):

    $ grub-install /dev/hda

This command installs GRUB into the MBR of the first hard drive. The grub-install options are

--force-lba

Force GRUB to use LBA mode, to allow booting from partitions beyond cylinder 1024.

--grub-shell=file

Specify that file is to be used as the GRUB shell. You might want to use this option to append options to grub. For example:

    $ grub-install --grub-shell="grub --read-only" /dev/fd0

-h, help

Print a help message on standard output and exit.

--recheck

Force probing of a device map. You should run grub-install with this option if you add or remove a disk from your system. The device map is found at /boot/grub/device.map.

--root-directory=dir

Install GRUB images in the directory dir instead of the GRUB root directory.

-v, --version

Print the GRUB version number to standard output and exit.

4.3.1.3 Installing from the GRUB command line

To install GRUB from the native command environment, make a GRUB boot floppy as described previously. You will use that floppy to boot to the GRUB command line to do the installation. If you know which partition holds the GRUB files, you're all set. Otherwise, you can find the partition with the find command:

    grub> find /boot/grub/stage1
    (hd0,0)

Here, the files are on (hd0,0). Use that information to set the GRUB root device:

    grub> root (hd0,0)

Run the setup command to install GRUB. To install GRUB on the MBR, run setup as follows:

    grub> setup (hd0)

If you are going to chainload Linux and want to install GRUB on the boot sector of the Linux partition, run setup like this:

    grub> setup (hd0,0)

4.3.2. The GRUB Configuration File

GRUB uses a configuration file that sets up the menu interface. The configuration file is called grub.conf and is found with the other GRUB files in the /boot/grub directory. grub.conf is also known as menu.lst, and at least on some distributions (e.g., Red Hat and SUSE), menu.lst is a symbolic link to grub.conf.

The configuration file begins with a section containing global commands that apply to all boot entries, followed by an entry for each Linux image or other operating system that you want to be able to boot. Here is an example of a global section (a hash sign, #, begins a comment):

    default=0                                  # default to the first entry
    timeout=20                                 # set the timeout to 20 seconds
    splashimage=(hd0,0)/grub/splash.xpm.gz     # the splash image displayed with
                                               # the menu

Certain GRUB commands are available only in the global section of the configuration file, for use with the GRUB menu. These commands are described in the following list. All other commands can be used either in the configuration file or on the command line and are described later in GRUB Commands.."

default num

Set the default menu entry to num. The default entry is started if the user does not make a selection before the timeout time. Menu entries are numbered from 0. If no default is specified, the first entry (0) is used as the default.

fallback num

Specify the entry to be used if for any reason the default entry has errors. If this command is specified and the default doesn't work, GRUB boots the fallback entry automatically instead of waiting for user input.

hiddenmenu

Specify that the menu is not to be displayed. The user can press Esc before the end of the timeout period to have the menu displayed; otherwise the default entry is booted at the end of the timeout.

timeout time

Specify the timeout period, in seconds. The timeout is the amount of time GRUB waits for user input before booting the default entry.

title name

Start a new boot entry with specified name.

Following the global section, the configuration file includes an entry for each boot image. An entry begins with a title command that specifies the text that will appear on the menu for that entry when the system boots. A typical boot entry might look like this:

    title Linux 2.6.10
    root (hd0,1)
    kernel /vmlinuz-2.6.10 ro root=LABEL=/
    initrd /initrd-2.6.10

This entry provides the information GRUB needs to boot to Linux. When the menu is displayed, it will include an entry that says:

    Linux 2.6.10

The GRUB root is on the second partition of the first hard drive (hd0,1). The kernel command specifies which Linux kernel to run and passes some parameters to the kernel, and the initrd command sets up an initial RAM disk.

The configuration file also provides some security features, such as the ability to set passwords and to lock certain entries so only the root user can boot them. The configuration file can be set up so that a password is required to run interactively (i.e., for editing menu entries or using the command interface) or simply to protect certain menu entries while leaving other entries available to all users. See the explanation of the password and lock commands in GRUB Commands.," later in the chapter.

In addition to providing a password feature, GRUB provides the command md5crypt to encrypt passwords in MD5 format, and a corresponding Linux command, grub-md5-crypt. grub-md5-crypt is a shell script that acts as a frontend to the grub shell, calling md5crypt. Passwords encrypted either directly with md5crypt or with grub-md5-crypt can be used with the password command to set up a GRUB password. grub-md5-crypt has three possible options:

--help

Print help message and exit.

--grub-shell=file

Specify that file is to be used as the GRUB shell.

--version

Print version information and exit.

4.3.3. Using the Menu Interface

The most common way to use GRUB is with the menu interface. The Stage 2 loader reads the configuration file grub.conf and displays the menu. If a timeout is set in the configuration file, GRUB displays a countdown at the bottom of the window showing how much time is left before it boots to the default entry. Move the cursor to an entry and press Enter to boot; or, press e to edit the command line for that entry, a to modify the kernel arguments, or c to go to the command-line interface to issue commands manually.

If you go to the command line, you can return to the menu at any time by pressing Esc.

Selecting a and e are similar, except that a displays only the kernel command line and lets you append options to it, while e displays the entire boot entry for you to edit. In either case, the available editing commands are similar to those available on the shell command line. When you are through editing, press Esc to return to the main menu. Your changes take effect for this session only; the configuration file is not permanently changed.

One common use for editing a kernel command is to boot to single-user mode. To do that, select a from the menu and append the word "single" to the end of the kernel command. Then press Esc to return to the menu and select the entry.

4.3.4. The GRUB Shell

In addition to using the command line from within the GRUB menu interface (or booting directly to the command line), you can run a GRUB shell directly from the Linux command line with the grub command. For the most part, using the grub shell is the same as running in the native command-line environment. The major difference is that the shell uses operating system calls to emulate the BIOS calls that the native environment uses. That can lead to some differences in behavior.

The syntax of the grub command is:

    grub [options]

For example:

    $ grub --no-floppy

The grub command-line options are:

--batch

Turn on batch mode for noninteractive use. Equivalent to grub --no-config-file --no-curses --no-pager.

--boot-drive=drive

Use drive as the Stage 2 boot drive, specified as a decimal, hexadecimal, or octal integer. The default is hexadecimal 0x0.

--config-file=file

Use file as the GRUB configuration file. The default is /boot/grub/grub.conf.

--device-map=file

Use file for the device map. The value of file is usually /boot/grub/device.map.

--help

Display a help message to standard output and exit.

--hold

Wait for a debugger to attach before starting grub.

--install-partition=partition

Use partition as the Stage 2 installation partition, specified as a decimal, hexadecimal, or octal number. The default is hexadecimal 0x20000.

--no-config-file

Run without reading the configuration file.

--no-curses

Don't use the curses interface for managing the cursor on the screen.

--no-floppy

Don't probe for a floppy drive. This option is ignored if --device-map is also specified.

--no-pager

Don't use the internal pager.

--preset-menu

Use a preset menu, for example if your system has no console and you need to get a serial terminal set up to see messages. To use this option, compile GRUB with the --enable-preset-menu=file option and create a menu file. See the GRUB documentation for more information.

--probe-second-floppy

Probe the second floppy drive (which is not probed by default). This option is ignored if --device-map is also specified.

--read-only

Do not write to any disk drives.

--verbose

Print verbose messages.

--version

Print version information and exit.

When you run grub, you will see something like this:

        GRUB  version 0.94  (640K lower / 3072K upper memory)

     [ Minimal BASH-like line editing is supported.  For the first word, TAB
       lists possible command completions.  Anywhere else TAB lists the possible
       completions of a device/filename. ]

    grub>

You can now enter commands at the grub> prompt. Press Tab to get a brief help message, listing all the commands:

    grub>
    Possible commands are: blocklist boot cat chainloader cmp color configfile
    debug device displayapm displaymem dump embed find fstest geometry halt help
    hide impsprobe initrd install ioprobe kernel lock makeactive map md5crypt
    module modulenounzip pager partnew parttype password pause quit read reboot
    root rootnoverify savedefault serial setkey setup terminal testload testvbe
    unhide uppermem vbeprobe

Using Tab is a quick way to remind yourself of the commands, but it can be confusing to see them all run together and wrapping across lines. You can also run the help command, which lists the most frequently used commands and their syntax:

    grub> help
    blocklist FILE                         boot
    cat FILE                               chainloader [--force] FILE
    color NORMAL [HIGHLIGHT]               configfile FILE
    device DRIVE DEVICE                    displayapm
    displaymem                             find FILENAME
    geometry DRIVE [CYLINDER HEAD SECTOR [ halt [--no-apm]
    help [--all] [PATTERN ...]             hide PARTITION
    initrd FILE [ARG ...]                  kernel [--no-mem-option] [--type=TYPE]
    makeactive                             map TO_DRIVE FROM_DRIVE
    md5crypt                               module FILE [ARG ...]
    modulenounzip FILE [ARG ...]           pager [FLAG]
    partnew PART TYPE START LEN            parttype PART TYPE
    quit                                   reboot
    root [DEVICE [HDBIAS]]                 rootnoverify [DEVICE [HDBIAS]]
    serial [--unit=UNIT] [--port=PORT] [-- setkey [TO_KEY FROM_KEY]
    setup [--prefix=DIR] [--stage2=STAGE2_ terminal [--dumb] [--timeout=SECS] [--
    testvbe MODE                           unhide PARTITION
    uppermem KBYTES                        vbeprobe [MODE]

You can add the --all option to see all the commands.

To get help for a specific command, add the command name (e.g., help read). help treats the text you enter as a pattern; therefore, if you enter help find, you'll get help for the find command, but if you enter help module, you'll get help for both module and modulenounzip.


Section 4.4. GRUB Commands

4.4. GRUB Commands

The following sections describe two sets of commands. Both can be used at the GRUB command line. In addition, the first set can be used in the global section of the menu, and the second can be used in individual menu entries. A few commands can be used only on the GRUB shell command line; this is noted in the command entry. The commands default, fallback, hiddenmenu, timeout, and title are available only in the configuration file, for use with the menu interface. They are described in The GRUB Configuration File.," earlier in the chapter.

When running commands, if you find that you aren't sure how to complete a pathname, you can use the Tab key to find the possible completions. For example:

    grub> blocklist (hd0,1)/grub/[Tab]
    Possible files are: grub.conf splash.xpm.gz menu.lst device.map stage1
    stage2 e2fs_stage1_5 fat_stage1_5 ffs_stage1_5 jfs_stage1_5 minix_stage1_5
    reiserfs_stage1_5 vstafs_stage1_5 xfs_stage1_5
    grub> blocklist (hd0,1)/grub/stage2
    (hd0,1)33306+24,33332+231

4.4.1. Command-Line and Global Menu Commands

The commands available at the command line and in the global section of the configuration file are as follows.

bootp
bootp [--with-configfile]

Initialize a network device via the Bootstrap Protocol (BOOTP). This command is available only if GRUB was compiled with netboot support. If --with-configfile is specified, GRUB automatically loads a configuration file specified by your BOOTP server.

color
color normal [highlight]

Specify colors for the menu. normal represents the color used for normal menu text, while highlight represents the color used to highlight the line the cursor is on. Both normal and highlight are specified as two symbolic color names, for foreground and background color, separated by a slash. For example:

    color light-gray/blue cyan/black

You can prefix the foreground color with blink- (e.g., blink-cyan/red) to get a blinking foreground. The colors black, blue, green, cyan, red, magenta, brown, and light-gray can be specified for foreground or background. Additional colors that can be used only for the foreground are dark-gray, light-blue, light-green, light-cyan, light-red, light-magenta, yellow, and white.

device
device drive file

Specify a file to be used as a BIOS drive. This command is useful for creating a disk image and/or for fixing the drives when GRUB fails to determine them correctly. The device command is available only from within the grub shell, not from the native command line. For example:

    grub> device (fd0) /floppy-image
    grub> device (hd0) /dev/sd0

dhcp
dhcp [--with-configfile]

Initialize a network device via the DHCP protocol. Currently, this command is just an alias for bootp and is available only if GRUB was compiled with netboot support. If specified with --with-configfile, GRUB will fetch and load a configuration file specified by your DHCP server.

hide
hide partition

Hide the specified partition. This is useful when you are booting DOS or Windows and there are multiple primary partitions on one disk. Hide all but the one you want to boot. Also see unhide.

ifconfig
ifconfig [--server=server] [--gateway=gateway] [--mask=mask]
[--address=address]

Configure a network device manually. If no options are specified, displays the current network configuration. With the server address, gateway, netmask, and IP address specified, ifconfig configures the device. The addresses must be in dotted decimal format (e.g., 192.168.0.4), and the options can be specified in any order.

pager
pager [flag]

Enable or disable the internal pager by setting flag to on (enable) or off (disable).

partnew
partnew part type from to

Make a new primary partition, part, specified in GRUB syntax. type is the partition type, specified as a number in the range 0-0xff. from and to are the starting and ending sectors, specified as absolute numbers. Some of the common partition types are:

Type | Number
None | 0
FAT 16, lt 32M | 4
FAT 16, gt 32M | 6
FAT 32 | 0xb
FAT 32, with LBA | 0xc
WIN 95, extended | 0xf
EXT2FS | 0x83
Linux extended | 0x85
Linux RAID | 0xfd
FreeBSD | 0xa5
OpenBSD | 0xa6
NetBSD | 0xfd

parttype
parttype part type

Change the type of partition part to type. The type must be a number in the range 0-0xff. See partnew for a list of partition types.

password
password [--md5] passwd [file]

Set a password for the menu interface. If used in the global section of the configuration file, outside the menu entries, GRUB prompts for a password before processing an a, e, or c entered by the user. Once the password passwd has been entered, if no file was specified, GRUB allows the user to proceed. Otherwise, GRUB loads the file as a new configuration file and restarts Stage 2. If password appears in an individual menu entry, GRUB prompts for the password before continuing. Specify --md5 to tell GRUB that the password was encrypted with the md5crypt command.

rarp
rarp

Initialize a network device via the Reverse Address Resolution Protocol (RARP). This command is available only if GRUB was compiled with netboot support. The use of RARP is deprecated.

serial
serial [options]

Initialize a serial device. The serial port is not used for communication unless terminal is also specified. This command is available only if GRUB was compiled with serial support.

Options

--device=device

Specify the tty device to be used in the host operating system. This option can be used only in the grub shell.

--parity=parity

Specify the parity. The possible values are no, odd, and even; the default is no.

--port=port

Specify the I/O port. The value of port overrides any value specified for --unit.

--speed=speed

Specify the transmission speed (default is 9600).

--stop=num

Specify the number of stop bits. The value of num is either 1 or 2 (default is 1).

--unit=num

Specify the serial port to use. The value of num is a number in the range 0-3; the default is 0, corresponding to COM1.

--word=num

Specify the number of data bits. The value of num is a number in the range 5-8 (default is 8).

setkey
setkey [to-key from-key]

Configure the keyboard map for GRUB by mapping the key from-key to the key to-key. With no mappings specified, reset the keyboard map. setkey is useful for setting up international keyboards. Possible key values are letters; digits; one of the strings alt, backspace, capslock, control, delete, enter, escape, Fn (where n is one of the function key numbers), shift, tab; or one of the strings in the Key Value columns of the following table:

Key value | Character | Key value | Character
ampersand | & | asterisk | *
at | @ | backquote | `
backslash | \ | bar | |
braceleft | { | braceright | }
bracketleft | [ | bracketright | ]
caret | ^ | colon | :
comma | , | dollar | $
doublequote | " | equal | =
exclam | ! | greater | >
less | < | minus | -
numbersign | # | parenleft | (
parenright | ) | percent | %
period | . | plus | +
question | ? | quote | `
semicolon | ; | slash | /
space |  | tilde | ~
underscore | _ |  |

splashimage
splashimage file

Use the image in file as the background (splash) image. The file should be a gzipped .xpm (X pixmap) file, created with a 14-color palette at 640 x 480 resolution and specified with standard GRUB device syntax:

    splashimage=(hd0,0)/grub/splash.xpm.gz

Programs that you can use to create .xpm files include the GIMP, xv, and xpaint.

terminal
terminal [options] [console] [serial]

Specify a terminal for user interaction. This command is available only if GRUB was compiled with serial support. If both console and serial are specified, GRUB uses the first terminal where a key is pressed, or the first after the timeout has expired. If neither is specified, GRUB displays the current setting.

Options

--dumb

The terminal is a dumb terminal; if this option is not specified, the terminal is assumed to be VT100-compatible.

--lines=num

The terminal has num lines. The default is 24.

--silent

Suppress the prompt to hit any key (useful if your system does not have a terminal).

--timeout=secs

Specify the timeout in seconds.

tftpserver
tftpserver ipaddress

Specify a TFTP server, overriding the address returned by a BOOTP, DHCP, or RARP server. The IP address must be specified in dotted decimal format. This command is available only if GRUB was compiled with netboot support. This command is deprecated; use ifconfig instead.

unhide
unhide partition

Unhide the specified partition. This is useful when booting DOS or Windows when there are multiple primary partitions on one disk. You can unhide the partition you want to boot and hide the others.

4.4.2. Command-Line and Menu-Entry Commands

The commands available at the command line and in the individual menu entries of the configuration file are as follows.

blocklist
blocklist file

Print the specified file in blocklist notation, where file is an absolute pathname or a blocklist. For example:

    grub> blocklist (hd0,1)/grub/grub.conf
    (hd0,1)33746+2

boot
boot

Boot the operating system or chainloader that has been loaded. You need to run this command only if you are in the interactive command-line mode.

cat
cat file

Display the contents of the specified file.

chainloader
    chainloader [--force] file

Load file as a chainloader. You can use blocklist notation to specifiy the first sector of the current partition with +1. If --force is specified, the file is loaded forcibly.

cmp
cmp file1 file2

Compare the two files file1 and file2. Report differences by printing nothing if the files are identical, the sizes if they are different, or the bytes at an offset if they differ at that offset.

configfile
configfile file

Load file as the configuration file.

debug
debug

Toggle debug mode, which prints extra messages to show disk activity. The default debug mode is off.

displayapm
displayapm

Display Advanced Power Management (APM) BIOS information.

displaymem
displaymem

Display the system address space map of the machine, including all regions of physical RAM installed. For example:

    grub> displaymem
     EISA Memory BIOS Interface is present
     Address Map BIOS Interface is present
     Lower memory: 640K, Upper memory (to first chipset hole): 3072K
     [Address Range Descriptor entries immediately follow (values are 64-bit)]
       Usable RAM:  Base Address:  0x0 X 4GB + 0x0,
          Length:   0x0 X 4GB + 0xa0000 bytes
       Reserved:  Base Address:  0x0 X 4GB + 0xa0000,
          Length:   0x0 X 4GB + 0x60000 bytes
       Usable RAM:  Base Address:  0x0 X 4GB + 0x100000,
          Length:   0x0 X 4GB + 0x300000 bytes

dump
dump from to

Dump the contents of one file into another. The file you're dumping from is a GRUB file, and the file you're dumping to is an operating system file.

embed
embed stage1.5 device

Embed the specified Stage 1.5 file in the sectors following the MBR if device is a drive, or in the boot loader area if it is an FFS (Berkeley Fast File System) partition (or, in the future, a ReiserFS partition). If successful, print the number of sectors the Stage 1.5 file occupies. You don't usually need to run this command directly.

find
find file

Search all partitions for the specified file and print the list of devices where it was found. The filename specified should be an absolute filename, such as /boot/grub/stage1, or a blocklist.

fstest
fstest

Toggle the filesystem test mode, which prints data for device reads and the values being sent to the low-level routines. The install and testload commands turn off filesystem test mode. The test output is in the following format:

    <partition-offset-sector, byte-offset, byte-length>

for high-level reads in a partition, and:

    [disk-offset-sector]

for low-level sector requests from the disk.

geometry
geometry drive [cylinder head sector [total_sector]]

Print geometry information for drive. From the GRUB shell, you can specify the number of cylinders, heads, sectors, and total sectors to set the drive's geometry. If total_sector is omitted, it is calculated from the other values.

halt
halt [--no-apm]

Shut down the computer. The computer is halted with an APM BIOS call unless the option --noapm is specified.

help
help [--all] [patterns]

Provide help for built-in commands. With no options, show the command and any options or parameters for the most common commands. With --all, show the same information for all possible commands. If you specify a pattern (i.e., a partial command name) or a full command name, a more complete description of the command or commands matching the pattern is displayed.

impsprobe
impsprobe

Probe the Intel Multiprocessor Specification 1.1 or 1.4 configuration table and boot the CPUs that are found into a tight loop. This command can be used only in Stage 2.

initrd
initrd file [args]

Load an initial ramdisk file and pass any arguments.

install
install [options] stage1_file [d] dest_dev stage2_file [addr]
[p] [config_file] [real_config_file]

Perform a full GRUB install. See also the setup command, which acts as a frontend to install and is easier to use. The Stage 2 or Stage 1.5 file (both referred to as stage2_file here because they are loaded the same way) must be in its final install location (e.g., in the /boot/grub directory). install loads and validates stage1_file, installs a blocklist in the Stage 1 file for loading stage2_file as Stage 2 or Stage 1.5, and writes the completed Stage 1 file to the first block of the device dest_dev.

Options

--force-lba

If the BIOS has LBA support but might return the incorrect LBA bitmap (which sometimes happens), --force-lba forces install to ignore the incorrect bitmap.

--stage2=os_stage2_file

This option is required to specify the operating system name of the Stage 2 file if the filesystem where it is located cannot be unmounted.

Parameters

addr

Specify the address at which Stage 1 is to load Stage 2 or Stage 1.5. The possible values are 0x8000 for Stage 2 and 0x2000 for Stage 1.5. If omitted, GRUB determines the address automatically.

config_file

Specify the location of the configuration file for Stage 2.

d

Tell Stage 1 to look for the actual disk on which stage2_file was installed if it's not on the boot drive.

dest_dev

Specify the destination device. The final Stage 1 file is written to this device.

p

If present, the partition where stage2_file is located is written into the first block of Stage 2.

real_config_file

If stage2_file is really a Stage 1.5 file, real_config_file specifies the real configuration filename and is written into the Stage 2 configuration file.

stage1_file

Specify the Stage 1 file to be written.

stage2_file

Specify the file that Stage 1 is to load for Stage 2.

ioprobe
ioprobe drive

Probe the I/O ports used for drive and write the results to standard output.

kernel
kernel [--non-mem-option] file [...]

Load the kernel image from file. Any text following file is passed on as the kernel command line. After running this command, you must reload any modules. The option --type specifies the kernel type and is required only for loading a NetBSD ELF kernel; GRUB automatically determines other types. The possible values of type are linux, biglinux, freebsd, multiboot, netbsd, and openbsd. For Linux, --no-mem-option tells GRUB not to pass the mem= option to the kernel.

lock
lock

Lock the entry until a valid password is entered. This is used in a menu entry immediately after title to prevent nonroot users from executing the entry. This command is most useful in conjunction with the password command.

makeactive
makeactive

Set the active partition on the root disk to GRUB's root device. Use only on primary PC hard disk partitions.

map
map to from

Map the from drive to the to drive. You need to do this when chainloading an operating system such as Windows, if it is not on the first drive. For example, if Windows is on (hd1):

    grub> map (hd0) (hd1)
    grub> map (hd1) (hd0)

This swaps the mappings of the first and second hard drives, tricking Windows into thinking it's on the first drive so it can boot.

md5crypt
md5crypt

Prompt for a password and encrypt it in MD5 format for use with the password command.

module
module file [...]

Load the boot module file for a multiboot format boot image. Anything after the filename is passed as the module command line.

modulenounzip
modulenounzip files

Like module, except that automatic decompression is disabled.

pause
pause messages

Print the specified message and wait for a key to be pressed before continuing.

quit
quit

Used only from within the grub shell to exit from the shell. In the native command environment, use reboot instead to reboot the computer.

read
read addr

Read a 32-bit value from memory at the specified address and display it in hex.

reboot
reboot

Reboot the system.

root
root device [hdbias]

Set the root device to the specified device and attempt to mount it to get the partition size (and some additional information for booting BSD kernels). If you are booting a BSD kernel, you can specify hdbias to tell the kernel how many BIOS drive numbers are before the current one.

rootnoverify
rootnoverify device [hdbias]

Similar to root, but don't attempt to mount the partition. Used when you are booting a non-GRUB-readable partition such as Windows.

savedefault
savedefault

Save the current menu entry as the default. GRUB will default to that entry the next time you boot the system.

setup
setup [options] install_device [image_device]

Set up installation of GRUB and run the install command to actually install GRUB onto the device install_device. Find the GRUB images on image_device if it is specified; otherwise use the current root device as set by the root command. If install_device is a hard disk, embed a Stage 1.5 file in the disk if possible.

Options

--force-lba

Force install to use LBA mode. Specify this option if your BIOS supports LBA mode but you find that GRUB isn't working in LBA mode without it.

--prefix=dir

Specify the directory where the GRUB images are located. If not specified, GRUB searches for them in /boot/grub and /grub.

--stage2=os_stage2_file

Passed to install to tell GRUB the operating system name of the Stage 2 file.

testload
testload file

Read the contents of a file in different ways and compare the results to test the filesystem code. If no errors are reported and the final output reports an equal value for the reported variables i and filepos, then the filesystem is consistent and you can try loading a kernel.

testvbe
testvbe mode

For a VBE (VESA BIOS Extension) BIOS, test the specified VESA BIOS extension mode. You should see an animation loop, which you can cancel by pressing any key.

uppermem
uppermem kbytes

Tell GRUB to assume that only the specified number of kilobytes of upper memory are installed. You should need to use this command only for old systems, where not all the memory may be recognized.

vbeprobe
vbeprobe [mode]

For a VBE BIOS, probe VESA BIOS extension information. If mode is specified, the output shows only information for that mode; otherwise, all available VBE modes are listed.


Section 4.5. Dual-Booting Linux and Windows NT/2000/XP

4.5. Dual-Booting Linux and Windows NT/2000/XP

As mentioned earlier, when you run Windows NT, its boot loader expects to be the one in charge; therefore, the standard way to dual-boot Windows NT and Linux is to add Linux as an option on the NT boot menu. This section describes how to do that. The information provided here also applies to Windows 2000 and Windows XP, which use the NT loader.

To set up dual booting with the NT loader, you need to provide the loader with a copy of the Linux boot sector. We'll describe how to do that on a computer running Windows NT with an NTFS filesystem (note that Windows NT should be installed on your system already). See the NT OS "Loader+Linux mini-HOWTO" for more information and other alternatives.

You should have a Linux boot floppy or CD available so that if necessary you can boot Linux before the NT boot loader has been modified. You should also have a DOS-formatted floppy to transfer the boot sector to the Windows NT partition. If you are running LILO and it is already installed, you may need to modify /etc/lilo.conf as described later. Otherwise, install LILO or GRUB to the boot sector of the Linux partition; once the Linux boot manager is installed and you have a configuration file, you can set up the system for dual booting.

The following instructions assume your Linux partition is on /dev/hda2. If Linux is on another partition in your system, be sure to replace /dev/hda2 in the following examples with the correct partition. The instructions also assume that you have a floppy drive to make a diskette for transferring the boot sector to your NTFS filesystem. If you don't have a floppy drive, you will have to use some other means of doing the transfer. If you have an NT FAT partition, you can mount that on Linux and transfer the file there. Other possibilities include putting it on a CD, transferring it over a network to another system while you reboot to NT, or even emailing it to yourself and reading it from the NT side.

  1. If you are running LILO, specify the Linux root partition as your boot device in /etc/lilo.conf. If you are editing /etc/lilo.conf manually, your entry will look like this:

        boot=/dev/hda2

    and will be the same as the root= entry.

    If you are running GRUB, make sure your configuration file, /boot/grub/grub.conf, includes a menu entry for booting Linux. The exact values of the entries in the menu depend on the filename of the kernel image that you wish to boot. For example:

        title Linux 2.6.10
    root (hd0,1)
    kernel /vmlinuz-2.6.10 ro root=LABEL=/
    initrd /initrd-2.6.10

    You can then skip to Step 3.

  2. Run the lilo command to install LILO on the Linux root partition.

  3. At this point, if you need to reboot Linux, you'll have to use the boot floppy or CD because the NT loader hasn't been set up yet to boot Linux.

  4. From Linux, run the dd command to make a copy of the Linux boot sector:

        $ dd if=/dev/hda2 of=/bootsect.lnx bs=512 count=1

    This command copies one block, with a block size of 512 bytes, from the input file /dev/hda2 to the output file /bootsect.lnx. Note that if you are running GRUB, the boot sector is actually the stage1 file. (The output filename can be whatever makes sense to you; it doesn't have to be bootsect.lnx.)

  5. Copy bootsect.lnx to a DOS-formatted floppy disk if that is how you are going to transfer it to NT:

        $ mount -t msdos /dev/fd0 /mnt
    $ cp /bootsect.lnx /mnt
    $ umount /mnt

  6. Reboot the system to Windows NT and copy the boot sector from the floppy disk to the hard disk. You can drag and drop the file to the hard drive, or use the command line to copy the file, as in the following example:

        C:> copy a:\bootsect.lnx c:\bootsect.lnx

    It doesn't matter where on the hard drive you put the file because you'll tell the NT loader where to find it in Step 8.

  7. Modify the attributes of the file boot.ini[*] to remove the system and read-only attributes so you can edit it:

    [*] boot.ini is the Windows NT counterpart to /etc/lilo.conf. It defines what operating systems the NT loader can boot.

        C:> attrib -s -r c:\boot.ini

  8. Edit boot.ini with a text editor to add the line:

        C:\bootsect.lnx="Linux"

    This line adds Linux to the boot menu and tells the Windows NT boot loader where to find the Linux boot sector. You can insert the line anywhere in the [operating systems] section of the file. Its position in the file determines where it will show up on the boot menu when you reboot your computer. Adding it at the end, for example, results in a boot.ini file that looks something like this (the second multi(0) entry is wrapped to fit the margins of this page):

        [boot loader]
    timeout=30
    default=multi(0)disk(0)rdisk(0)partition(1)\WINNT
    [operating systems]
    multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT Server Version 4.00"
    multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT Server Version
    4.00 [VGA mode]" /basevideo /sos
    C:\bootsect.lnx="Linux"

    If you want Linux to be the default operating system, modify the default= line:

        default=C:\bootsect.lnx

  9. Rerun attrib to restore the system and read-only attributes:

        C:> attrib +s +r c:\boot.ini

Now you can shut down Windows NT and reboot. NT will prompt you with a menu that looks something like this:

    OS Loader V4.00

    Please select the operating system to start:

    Windows NT Workstation Version 4.00
    Windows NT Workstation Version 4.00 [VGA mode]
    Linux

Select Linux, and the NT loader will read the Linux boot sector and transfer control to LILO or GRUB on the Linux partition.

If you are using LILO and you later modify /etc/lilo.conf or rebuild the kernel, you need to rerun the lilo command, create a new bootsect.lnx file, and replace the version of bootsect.lnx on the Windows NT partition with the new version. In other words, you need to rerun Steps 2-6.

NOTE

If you have any problems or you simply want to remove LILO or GRUB later, you can reverse the installation procedure: boot to Windows NT, change the system and read-only attributes on boot.ini, re-edit boot.ini to remove the Linux entry, save the file, restore the system and read-only attributes, and remove the Linux boot sector from the NT partition.


Section 4.6. Boot-Time Kernel Options

4.6. Boot-Time Kernel Options

The earlier sections of this chapter described some of the options you can specify when you boot Linux. There are many more options that can be specified. This section touches on the ways to pass options to the kernel and then describes some of the kinds of parameters you might want to use. The parameters in this section affect the kernel and therefore apply regardless of which boot loader you use.

As always with Unix systems, there are a number of choices for the boot process itself. If you are using Loadlin, you can pass parameters to the kernel on the command line or in a file.

If LILO is your boot loader, you can add to or override the parameters specified in /etc/lilo.conf during the boot process as follows:

  • If prompt is set in /etc/lilo.conf, LILO always presents the boot prompt and waits for input. At the prompt, you can choose the operating system to be booted. If you choose Linux, you can also specify parameters.

  • If prompt isn't set, press Ctrl, Shift, or Alt when the word "LILO" appears. The boot prompt will then appear. You also can press the Scroll Lock key before LILO is printed and not have to wait poised over the keyboard for the right moment.

  • At the boot prompt, specify the system you want to boot, or press Tab to get a list of the available choices. You then can enter the name of the image to boot. For example:

        LILO boot: <press Tab>
    linux   test   dos
    boot: linux

    You also can add boot command options:

        boot: linux single

  • If you don't provide any input, LILO waits the amount of time specified in the delay parameter and then boots the default operating system with the default parameters, as set in /etc/lilo.conf.

    If you are using GRUB, you can pass parameters to the kernel on the kernel command line, either in the configuration file or from the command-line interface. If you are booting from the GRUB menu, you can edit or add parameters by entering e or a when the menu appears.

    Some of the boot parameters have been mentioned earlier. Many of the others are hardware-specific and are too numerous to mention here. For a complete list of parameters and a discussion of the booting process, see the "BootPrompt HOWTO." Some of the parameters not shown earlier that you might find useful are listed next; many more are covered in the HOWTO. Most of the following parameters are used to provide information or instructions to the kernel, rather than to LILO or GRUB.

acpi=off

Disable ACPI (Advanced Configuration and Power Interface) if it was to be enabled. This is useful for debugging possible hardware problems.

debug

Print all kernel messages to the console.

hd=cylinders,heads,sectors

Specify the hard drive geometry to the kernel. Useful if Linux has trouble recognizing the geometry of your drive, especially if it's an IDE drive with more than 1024 cylinders.

load_ramdisk=n

Tell the kernel whether to load a RAM disk image for use during Linux installation. Values of n are:

0 Don't try to load the image. This is the default.

1 Load the image from a floppy disk to the RAM disk.

mem=size

Specify the amount of system memory installed. Useful if your BIOS reports memory only up to 64 MB and your system has more memory installed. Specify as a number with M or k (case-insensitive) appended:

    mem=128M

Because mem would have to be included on the command line for every boot, it often is specified on a command line saved with lock or with append to be added to the parameters passed to the kernel.

noinitrd

When set, disable the two-stage boot and preserve the contents of /dev/initrd so the data is available after the kernel has booted. /dev/initrd can be read only once, and then its contents are returned to the system.

number

Start Linux at the runlevel specified by number. A runlevel is an operating state that the system can be booted to, such as a multiuser system or a system configuration running the X Window System. A runlevel is generally one of the numbers from 1 to 6; the default is usually 3. The runlevels and their corresponding states are defined in the file /etc/inittab. See the manpage for /etc/inittab for more information.

ro Mount the root filesystem read-only. Used for doing system maintenance, such as checking the filesystem integrity, when you don't want anything written to the filesystem.

rw Mount the root filesystem read/write. If neither ro nor rw is specified, the default value (usually rw) stored in the kernel image is used.

single

Start Linux in single-user mode. This option is used for system administration and recovery. It gives you a root prompt as soon as the system boots, with minimal initialization. No other logins are allowed.


Section 4.7. initrd: Using a RAM Disk

4.7. initrd: Using a RAM Disk

Modern Linux distributions use a modular kernel, which allows modules to be added without requiring that the kernel be rebuilt. If your root filesystem is on a device whose driver is a module (as is frequently true of SCSI disks), you can use the initrd facility, which provides a two-stage boot process, to first set up a temporary root filesystem in a RAM disk containing the modules you need to add (e.g., the SCSI driver) and then load the modules and mount the real root filesystem. The RAM disk containing the temporary filesystem is the special device file /dev/initrd.

Similarly, you need to use a RAM disk if your root partition uses the ext3 filesystem and ext3 was not compiled into the kernel image. In that case, the ext3 module must be loaded with initrd.

Before you can use initrd, both RAM disk support (CONFIG_BLK_DEV_RAM=y) and initial RAM disk support (CONFIG_BLK_DEV_INITRD=y) must be compiled into the Linux kernel. Then you need to prepare the normal root filesystem and create the RAM disk image. Your Linux distribution may have utilities to do some of the setup for you; for example, the Red Hat distribution comes with the mkinitrd command, which builds the initrd image. For detailed information, see the initrd manpage and the file initrd.txt (the path may vary, but it is usually something like /usr/src/linux/Documentation/initrd.txt).

Once your Linux system has been set up for initrd, you can do one of the following, depending on which boot loader you are using:

  • If you are using LILO, add the initrd option to the appropriate image section:

        image=/vmlinuz
      initrd=/boot/initrd  # The file to load as the contents of /dev/initrd
      ...

    Run the /sbin/lilo command, and you can reboot with initrd.

  • If you are using GRUB, add the initrd option to the kernel line of the configuration-file boot entry, or to the kernel command if you are booting from the command-line interface:

        kernel /vmlinuz-2.6.10 ro root=LABEL=/
    initrd /initrd-2.6.10

  • If you are using Loadlin, add the initrd option to the command line:

        loadlin c:\linux\vmlinuz initrd=c:\linux\initrd


Chapter 5. Package Management

This chapter describes the two major Linux packaging systems: the Red Hat Package Manager (RPM) and the Debian GNU/Linux Package Manager. It also describes the major frontend applications designed to simplify and automate package management: yum and up2date for RPM-based systems, aptitude and synaptic for Debian-based systems, and apt, which is a Debian package-management tool that is now also available for RPM-based systems.

When you install applications on your Linux system, most often you'll find a binary or a source package containing the application you want, instead of (or in addition to) a .tar.gz file. A package is a file containing the files necessary to install an application. However, while the package contains the files you need for installation, the application might require the presence of other files or packages that are not included, such as particular libraries (and even specific versions of the libraries), to actually be able to run. Such requirements are known as dependencies.

Package-management systems offer many benefits. As a user, you may want to query the package database to find out what packages are installed on the system and their versions. As a system administrator, you need tools to install and manage the packages on your system. And if you are a developer, you need to know how to build a package for distribution.

Among other things, package managers do the following:

  • Provide tools for installing, updating, removing, and managing the software on your system.

  • Allow you to install new or upgraded software directly across a network.

  • Tell you what software package a particular file belongs to or what files a package contains.

  • Maintain a database of packages on the system and their status, so you can determine what packages or versions are installed on your system.

  • Provide dependency checking, so you don't mess up your system with incompatible software.

  • Provide GPG, PGP, MD5, or other signature-verification tools.

  • Provide tools for building packages.

Any user can list or query packages. However, installing, upgrading, or removing packages generally requires root privileges. This is because the packages normally are installed in system-wide directories that are writable only by root. Sometimes you can specify an alternate directory to install a package into your home directory or into a project directory where you have write permission, if you aren't running as root.

Signature verification is an important feature of package-management systems that helps maintain the security of your system. An MD5 checksum is used to check the integrity of a package, making sure, for example, that it was downloaded correctly and that it was not tampered with by a malicious user. GPG (and PGP) encrypt a digital signature into the package, which is used to verify the identity of the package creator.

Most often you'll install a binary package, in which the source code has been compiled and the software is ready to run once it is installed. You may also want or need to install source packages, which provide the source code and instructions for compiling and installing it. Source code packages do not contain executable files. Packages follow certain naming conventions, and you can tell from the name whether it is a binary or source package. RPM and Debian package names contain the same information, but they are expressed slightly differently. An RPM package has the form:

    package-version-release.architecture.rpm

A Debian package has the form:

    package_version-revision_architecture.deb

In both cases, package is the name of the package, version is the version number of the software, release (RPM) and revision (Debian) indicate the revision number of the package for that version, and architecture shows what system architecture the software was packaged for (e.g., i386 or m68k). The value of architecture may also be noarch for a package that is not hardware-specific or src for an RPM source package (Debian source packages come as tarred, gzipped files).

All the package managers check for dependencies when you install a package. In the case of RPM, if there are missing dependencies, it prints an error and terminates without installing the package. To proceed, you need to first install the missing package (or packages). This can become an involved process if the missing package has its own dependencies. A major advantage of the high-level package managers described in this chapter (i.e., apt, yum, up2date, synaptic, and aptitude) is that they automatically resolve dependencies and install missing packages for you. Another advantage is that they locate and download the package automatically, based on information in configuration files specifying where to look for packages. With RPM, you first have to locate the package, then download it, and only then can you run RPM to do the install. On the other hand, if you already have the package file on your system or on a CD, RPM is quick and easy to run.

Both RPM and the apt system back up old files before installing an updated package. Not only does this let you go back if there is a problem, but it also ensures that you don't lose your changes (to configuration files, for example).

The following list shows the package-management programs described in the rest of this chapter. Which program to use is very much a matter of personal preference, and you can use more than one at different times. However, it's best to pick the program you prefer and use it consistently, so all your packages are maintained in a single database that you can query.

The Advanced Package Tool (APT)

APT is a modern, user-friendly package-management tool that consists of a number of commands. The most frequently used of these commands is apt-get, which is used to download and install a Debian package. apt-get can be run from the command line or selected as a method from dselect. One of the features of apt-get is that you can use it to get and install packages across the Internet by specifying an FTP or HTTP URL. You can also use it to upgrade all packages currently installed on your system in a single operation.

Note that there are versions of the apt commands that can be used on an RPM-based system. If you plan to do that, it's best to install the version of apt that comes with your Linux distribution.

aptitude

High-level text-based interface to APT. Runs either from the command line or in a visual mode inside a terminal window such as an xterm.

dpkg

The original Debian packaging tool. Used to install or uninstall packages, or as a frontend to dpkg-deb. Getting and installing packages is usually done with apt-get, but dpkg is still commonly used to install a package that is already on your system. In fact, apt-get calls dpkg to do the installation once it's gotten the package.

dpkg-deb

Lower-level packaging tool. Used to create and manage the Debian package archives. Accepts and executes commands from dpkg or can be called directly.

dselect

An interactive frontend to dpkg. With the advent of the newer tools and the increased number of packages, the use of dselect is deprecated.

RPM

The original command-line system for installing and managing RPM packages. RPM has two commands: rpm for installing and managing packages, and rpmbuild for creating packages.

synaptic

A graphical frontend to APT.

up2date

A graphical frontend to RPM.

yum

A frontend to RPM that runs from the command line.

If you want to update your system daily, to keep it current and to be sure you have the latest security fixes, you can set up a command that you can reissue every day, or you can set it up as a cron job to run overnight. (See the descriptions of the cron and crontab commands in Chapter 3 for more information on setting up a cron job.)

For example, with apt-get, you can set up the command:

    apt-get update && apt-get -u dist-upgrade>

This command runs apt-get twice: first to update the local package lists, and then to actually do the upgrade. The dist-upgrade command handles all dependencies when it does the upgrade, and the -u option prints a list of the packages being upgraded.

yum, on the other hand, comes with acron job that can be run daily. This job first updates yum itself, then updates all the remaining packages:

    #!/bin/sh

    if [ -f /var/lock/subsys/yum ]; then
            /usr/bin/yum -R 10 -e 0 -d 0 -y update yum
            /usr/bin/yum -R 120 -e 0 -d 0 -y update
    fi

The -R option sets a maximum time, in minutes, for yum to wait before running the command, -e sets the error level to 0 to print only critical errors, -d specifies a debug level of 0 to print no debugging messages, and -y assumes "yes" as the answer to any questions.


Section 5.1. The Red Hat Package Manager

5.1. The Red Hat Package Manager

The Red Hat Package Manager (RPM) is a freely available packaging system for software distribution and installation. In addition to the Red Hat Enterprise Linux and Fedora Core distributions, both SUSE and Mandrake are among the Linux distributions that use RPM.

Using RPM is straightforward. A single command, rpm, has options to perform all package-management functions except building packages.[*] For example, to find out if the Emacs editor is installed on your system, you could enter:

[*] In older versions of RPM, the build options were part of the rpm command.

    $ rpm -q emacs
    emacs-21.3-17

This command prints the full package name, confirming its presence.

The rpmbuild command is used to build both binary and source packages.

5.1.1. RPM Package Concepts

This section provides an overview of some of the parts of an RPM package. Much of the information is of primary use to developers, but because some of the terms are referenced in the RPM command descriptions, they are explained briefly here.

An RPM package has three primary components. The header contains all the information about the package, such as its name and version, a description, a list of included files, the copyright terms, and where the source file can be found. The signature contains information used to verify the integrity and authenticity of the package. The archive contains the actual files that make up the package.

When a package is being built, one of the requirements for its developers is to create a spec file. If you download the source rpm for a package, you can look at the spec file; it has a filename of package.spec (e.g., yum.spec for the yum spec file). The spec file contains all the information required to build a package, including a description of the software, instructions telling the rpmbuild command how to build the package, and a list of the files included and where they get installed. Some other features of spec files include the following:

Macros

Macros are sequences of commands stored together and executed by invoking the macro name. The RPM build process provides two standard macros: %setup to unpack the original sources and %patch to apply patches. Other macros appear later in this chapter in the command descriptions and are described there.

Scripts

Scripts are used to control the build process. Some of the scripts RPM uses include %prep to begin the build process, %build primarily to run make and perhaps do some configuration, %install to do a make install and %clean to clean up afterward. Four additional scripts may be created to run when a package is actually installed on a system. These scripts are %pre for scripts run before package installation, %post for scripts run after package installation, %preun for scripts run before a package is uninstalled, and %postun for scripts run after a package is uninstalled.

Trigger scriptlets

Trigger scriptlets are extensions of the normal install and uninstall scripts. They provide for interaction between packages. A trigger scriptlet provided with one package will be triggered to run by the installation or removal of some other package. For example, a newly installed RPM package may cause an existing application to run or restart once installation is complete. In many cases, a newly installed package requires services to be restarted.

5.1.2. The rpm Command

RPM packages are built, installed, and queried with the rpm command. RPM package filenames usually end with a .rpm extension. rpm has a set of modes, each with its own options. The format of the rpm command is:

    rpm [options] [packages]

With a few exceptions, as noted in the lists of options that follow, the first option specifies the rpm mode (install, query, update, etc.), and any remaining options affect that mode.

Options that refer to packages are sometimes specified as package-name and sometimes as package-file. The package name is the name of the program or application, such as xpdf. The package file is the name of the RPM file, such as xpdf-3.00-10.1.i386.rpm.

RPM provides a configuration file for specifying frequently used options. The default global configuration file is usually /usr/lib/rpm/rpmrc, the local system configuration file is /etc/rpmrc, and users can set up their own $HOME/.rpmrc files. You can use the --showrc option to show the values RPM will use by default for all the options that may be set in an rpmrc file:

    rpm --showrc

The rpm command includes FTP and HTTP clients, so you can specify an ftp:// or http:// URL to install or query a package across the Internet. You can use an FTP or HTTP URL wherever package-file is specified in the commands presented here. Be careful, however, when downloading packages from the Internet. Always verify package contents by checking MD5 hashes and signatures. Whenever possible, install from trusted media.

Any user can query the RPM database. Most of the other functions, such as installing and removing packages, require superuser privileges.

5.1.2.1 General options

The following options can be used with all modes:

--dbpath path

Use path as the path to the RPM database instead of the default /var/lib/rpm.

-?, --help

Print a long usage message (running rpm with no options gives a shorter usage message).

--quiet

Display only error messages.

--rcfile filelist

Get configuration from the files in the colon-separated filelist. If --rcfile is specified, there must be at least one file in the list and the file must exist. filelist defaults to /usr/lib/rpm/rpmrc:/usr/lib/rpm/redhat/rpmrc:/etc/rpmrc:~/.rpmrc. Use with --showrc to see what options will be used if alternate configuration files are specified.

--root dir

Perform all operations within the directory tree rooted at dir.

-v

Verbose. Print progress messages.

--version

Print the version number of rpm.

-vv

Print debugging information.

5.1.2.2 Install, upgrade, and freshen options

Use the install command to install or upgrade an RPM package. Upgrading with install leaves any existing versions on the system. The install syntax is:

    rpm -i [install-options] package_file ...
    rpm --install [install-options] package_file ...

To install a new version of a package and remove an existing version at the same time, use the upgrade command instead:

    rpm -U [install-options] package_file ...
    rpm --upgrade [install-options] package_file ...

If the package doesn't already exist on the system, -U acts like -i and installs it. To prevent that behavior, you can freshen a package instead; in that case, rpm upgrades the package only if an earlier version is already installed. The freshen syntax is:

    rpm -F [install-options] package_file ...
    rpm --freshen [install-options] package_file ...

For all forms, package-file can be specified as an FTP or HTTP URL to download the file before installing it. See FTP/HTTP options.," later in this chapter.

The installation and upgrade options are:

--aid

If rpm suggests additional packages, add them to the list of package files.

--allfiles

Install or upgrade all files.

--badreloc

Used with --relocate to force relocation even if the package is not relocatable.

--excludedocs

Don't install any documentation files.

--excludepath path

Don't install any file whose filename begins with path.

--force

Force the installation. Equivalent to --replacepkgs --replacefiles --oldpackage.

-h, --hash

Print 50 hash marks as the package archive is unpacked. Use this option with -v or --verbose for a nicer display.

--ignorearch

Install even if the binary package is intended for a different architecture.

--ignoreos

Install binary package even if the operating systems don't match.

--ignoresize

Don't check disk space availability before installing.

--includedocs

Install documentation files. This is needed only if excludedocs: 1 is specified in an rpmrc file.

--justdb

Update the database only; don't change any files.

--nodeps

Don't check whether this package depends on the presence of other packages.

--nodigest

Don't verify package or header digests.

--noorder

Don't reorder packages to satisfy dependencies before installing.

--nopost

Don't execute any post-install script.

--nopostun

Don't execute any post-uninstall script.

--nopre

Don't execute any pre-install script.

--nopreun

Don't execute any pre-uninstall script.

--noscripts

Don't execute any pre-install or post-install scripts. Equivalent to specifying --nopre --nopost --nopreun --nopostun.

--nosignature

Don't verify package or header signatures.

--nosuggest

Don't suggest packages that provide a missing dependency.

--notriggerin

Don't execute any install trigger scriptlet.

--notriggerun

Don't execute any uninstall trigger scriptlet.

--notriggerpostun

Don't execute any post-uninstall trigger scriptlet.

--notriggers

Don't execute any scripts triggered by package installation. Equivalent to specifying --notriggerin --notriggerun --notriggerpostun.

--oldpackage

Allow an upgrade to replace a newer package with an older one.

--percent

Print percent-completion messages as files are unpacked. Useful for running rpm from other tools.

--prefix path

Set the installation prefix to path for relocatable binary packages.

--relocate oldpath=newpath

For relocatable binary files, change all file paths from oldpath to newpath. Can be specified more than once to relocate multiple paths.

--repackage

Repackage the package files before erasing an older version, to save the package in case a transaction rollback is necessary. Rename the package as specified by the macro %_repackage_name_fmt, and save it in the directory specified by the macro %_repackage_dir (by default /var/spool/repackage). The repackaged file is not identical to the original package.

--replacefiles

Install the packages even if they replace files from other installed packages.

--replacepkgs

Install the packages even if some of them are already installed.

--test

Go through the installation to see what it would do, but don't actually install the package. This option lets you test for problems before doing the installation.

5.1.2.3 Query options

The syntax for the query command is:

    rpm -q [package-options] [information-options]
    rpm --query [package-options] [information-options]

There are two subsets of query options. Package-selection options determine which packages to query, and information-selection options determine which information to provide.

5.1.2.4 Package-selection options

package_name

Query the installed package package_name.

-a, --all

Query all installed packages.

-f file, --file file

Find out which package owns file.

--fileid md5

Query package with the specified MD5 digest.

-g group, --group group

Find out which packages have group group.

--hdrid sha1

Query package with the specified SHA1 digest in the package header.

-p package_file, --package package_file

Query the uninstalled package package_file, which can be a URL. If package_file is not a binary package, it is treated as a text file containing a package manifest, with each line of the manifest containing a path or one or more whitespace-separated glob expressions to be expanded to paths. These paths are then used instead of package_file as the query arguments. The manifest can contain comments that begin with a hash mark (#).

--pkgid md5

Query the package with a package identifier that is the given MD5 digest of the combined header and contents.

--querybynumber num

Query the numth database entry. Useful for debugging.

-qf, --queryformat string

Specify the format for displaying the query output, using tags to represent different types of data (e.g., NAME, FILENAME, DISTRIBUTION). The format specification is a variation of the standard printf formatting, with the type specifier omitted and replaced by the name of the header tag inclosed in brackets ({ }). For example:

    %{NAME}

The tag names are case-insensitive. Use --querytags (see Miscellaneous options.," later in this section) to view a list of available tags. The tag can be followed by :type to get a different output format type. The possible types are:

:armor

Wrap a public key in ASCII armor.

:base64

Encode binary data as base64.

:date

Use %c format as in strftime(3)to display the preferred date and time format for this locale.

:day

Use %a %b %d %Y format as in the function strftime(3). This format displays the day, the month, the month as a decimal number, and the four-digit year.

:depflags

Format dependency flags.

:fflags

Format file flags.

:hex

Use hexadecimal format.

:octal

Use octal format.

:perms

Format file permissions.

:shescape

Escape single quotes for use in a script.

:triggertype

Display trigger suffix (i.e., in, un, or postun, indicating whether it's an install, uninstall, or post-uninstall trigger).

--specfile specfile

Query specfile as if it were a package. Useful for extracting information from a spec file.

--tid tid

List packages with the specified transaction identifier (tid). The tid is a Unix timestamp. All packages installed or erased in a single transaction have the same tid.

--triggeredby pkg

List packages containing triggers that are run when the installation status of package pkg changes. For example:

    $ rpm -q --triggeredby glibc
    redhat-lsb-1.3-4

In this example, the package redhat-lsb-1.3.4 contains a triggerpostun scriptlet that runs after glibc is uninstalled.

--whatrequires capability

List packages that require the given capability to function. For example:

    $ rpm -q --whatrequires popt
    rpm-4.3.2-21
    gstreamer-0.8.7-3
    librsvg2-2.8.1-1
    planner-0.12.1-1

--whatprovides capability

List packages that provide the given capability. For example:

    $ rpm -q --whatprovides popt
    popt-1.9.1-21

5.1.2.5 Information-selection options

-c, --configfiles

List configuration files in the package. Implies -l.

--changelog

Display the log of change information for the package.

-d, --docfiles

List documentation files in the package. Implies -l.

--dump

Dump information for each file in the package. This option must be used with at least one of -l, -c, or -d. The output includes the following information in this order:

    path size mtime md5sum mode owner group isconfig isdoc rdev symlink

--filesbypkg

List all files in each package.

-i, --info

Display package information, including the name, version, and description. Formats the results according to --queryformat if specified.

-l, --list

List all files in the package.

--last

List packages by install time, with the latest packages listed first.

--provides

List the capabilities this package provides.

-R, --requires

List any packages this package depends on.

-s, --state

List each file in the package and its state. The possible states are normal, not installed, or replaced. Implies -l.

--scripts

List any package-specific shell scripts used during installation and uninstallation of the package.

--triggers, --triggerscript

Display any trigger scripts in the package.

5.1.2.6 Uninstall options

The syntax for erase, the uninstall command, is:

    rpm -e [uninstall-options ]package_name  ...
    rpm --erase [uninstall-options ]package_name  ...

The uninstall options are:

--allmatches

Remove all versions of the package. Only one package should be specified; otherwise, an error results.

--nodeps

Don't check dependencies before uninstalling the package.

--nopostun

Don't run any post-uninstall scripts.

--nopreun

Don't run any pre-uninstall scripts.

--noscripts

Don't execute any pre-uninstall or post-uninstall scripts. This option is equivalent to --nopreun --nopostun.

--notriggerpostun

Don't execute any post-uninstall scripts triggered by the removal of this package.

--notriggers

Don't execute any scripts triggered by the removal of this package. Equivalent to --notriggerun --notriggerpostun.

--notriggerun

Don't execute any uninstall scripts triggered by the removal of this package.

--repackage

Repackage the files before uninstalling them, to save the package in case a transaction rollback is necessary. Rename the package as specified by the macro %_repackage_name_fmt and save it in the directory specified by the macro %_repackage_dir (by default, /var/spool/repackage). The repackaged file is not identical to the original package file.

--test

Don't really uninstall anything; just go through the motions. Use with -vv for debugging.

5.1.2.7 Verify options

The syntax for the verify command is:

    rpm -V|--verify [package-selection-options] [verify-options]

Verify mode compares information about the installed files in a package with information about the files that came in the original package and displays any discrepancies. The information compared includes the size, MD5 sum, permissions, type, owner, and group of each file. Uninstalled files are ignored.

The package selection options include those available for query mode. In addition, the following verify options are available:

--nodeps

Ignore package dependencies.

--nodigest

Ignore package or header digests.

--nofiles

Ignore attributes of package files.

--nogroup

Ignore group ownership errors.

--nolinkto

Ignore symbolic-link errors.

--nomd5

Ignore MD5 checksum errors.

--nomode

Ignore file mode (permissions) errors.

--nordev

Ignore major and minor device number errors.

--nomtime

Ignore modification time errors.

--noscripts

Ignore any verify script.

--nosignature

Ignore package or header signatures.

--nosize

Ignore file size errors.

--nouser

Ignore user ownership errors.

The output is formatted as an eight-character string, possibly followed by an attribute marker, and then the filename. Each of the eight characters in the string represents the result of comparing one file attribute to the value of that attribute from the RPM database. A period (.) indicates that the file passed that test. The following characters indicate failure of the corresponding test:

5

MD5 sum

D

Device

G

Group

L

Symlink

M

Mode (includes permissions and file type)

S

File size

T

Mtime

U

User

The possible attribute markers are:

c

Configuration file

d

Documentation file

g

Ghost file (contents not included in package)

l

License file

r

Readme file

5.1.2.8 Database rebuild options

The syntax of the command to rebuild the RPM database is:

    rpm --rebuilddb [options]

You also can build a new database:

    rpm --initdb [options]

The options available with the database rebuild mode are the --dbpath, --root, and -v options described earlier under General options.."

5.1.2.9 Signature-check options

RPM packages may have a GPG signature built into them. There are three types of digital signature options: you can check signatures, add signatures to packages, and import signatures.

The syntax of the signature check mode is:

    rpm --checksig [options] package_file...
    rpm -K [options] package_file...

The signature-checking options -K and --checksig check the digests and signatures contained in the specified packages to insure the integrity and origin of the packages. Note that RPM now automatically checks the signature of any package when it is read; these options are still useful, however, for checking all headers and signatures associated with a package.

The --nosignature and --nodigest options described earlier under Verify options. are available for use with signature check mode.

The syntax for adding signatures to binary packages is:

    rpm --addsign binary-pkgfile ...
    rpm --resign binary-pkgfile ...

Both --addsign and --resign generate and insert new signatures, replacing any that already exist in the specified binary packages.[*]

[*] In older versions of RPM, --addsign was used to add new signatures without replacing existing ones, but currently both options work the same way and replace any existing signatures.

The syntax for importing signatures is:

    rpm --import public-key

The --import option is used to import an ASCII public key to the RPM database so that digital signatures for packages using that key can be verified. Imported public keys are carried in headers, and keys are kept in a ring, which can be queried and managed like any package file.

5.1.2.10 Miscellaneous options

Several additional rpm options are available:

--querytags

Print the tags available for use with the --queryformat option in query mode.

--setperms packages

Set file permissions of the specified packages to those in the database.

--setugids packages

Set file owner and group of the specified packages to those in the database.

--showrc

Show the values rpm will use for all options that can be set in an rpmrc file.

5.1.2.11 FTP/HTTP options

The following options are available for use with FTP and HTTP URLs in install, update, and query modes.

--ftpport port

Use port for making an FTP connection on the proxy FTP server instead of the default port. Same as specifying the macro %_ftpport.

--ftpproxy host

Use host as the proxy server for FTP transfers through a firewall that uses a proxy. Same as specifying the macro %_ftpproxy.

--httpport port

Use port for making an HTTP connection on the proxy HTTP server instead of the default port. Same as specifying the macro %_httpport.

--httpproxy host

Use host as the proxy server for HTTP transfers. Same as specifying the macro %_httpproxy.

5.1.3. RPM Examples

Query the RPM database to find Emacs-related packages:

    $ rpm -q -a | grep emacs

Query an uninstalled package, printing information about the package and listing the files it contains:

    $ rpm -qpil ~/downloads/bash2-doc-2.03-8.i386.rpm

Install a package (assumes superuser privileges):

    $ rpm -i sudo-1.6.7p5-30.1.i386.rpm

Do the same thing, but report on the progress of the installation:

    $ rpm -ivh sudo-1.6.7p5-30.1.i386.rpm

5.1.4. The rpmbuild Command

The rpmbuild command is used to build RPM packages. The syntax for rpmbuild is:

    rpmbuild -[b|t]stage [build-options] spec-file ...

Specify -b to build a package directly from a spec file, or -t to open a tarred, gzipped file and use its spec file.

Both forms take the following single-character stage arguments, which specify the stages, or steps, required to build a package. The stages are listed in the order they would be performed:

p

Perform the prep stage, unpacking source files and applying patches.

l

Do a list check, expanding macros in the files section of the spec file and verifying that each file exists.

c

Perform the prep and build stages; generally equivalent to doing a make.

i

Perform the prep, build, and install stages; generally equivalent to doing a make install.

b

Perform the prep, build, and install stages, then build a binary package.

s

Build a source package.

a

Perform the prep, build, and install stages, then build both binary and source packages.

The difference between the build stage, which is one of the early steps, and building a binary package in b or a is the difference between building a working binary for the software and putting all the pieces together into a final rpm package.

5.1.4.1 rpmbuild options

The general rpm options described earlier under General options. can be used with rpmbuild.

The following additional options can also be used when building an rpm file with rpmbuild:

--buildroot dir

Override the BuildRoot tag with dir when building the package.

--clean

Clean up (remove) the build files after the package has been made.

--nobuild

Go through the motions, but don't execute any build stages. Used for testing spec files.

--rmsource

Remove the source files when the build is done. Can be used as a standalone option with rpm to clean up files separately from creating the packages.

--rmspec

Remove the spec file when the build is done. Like --rmsource, --rmspec can be used as a standalone option with rpmbuild.

--short-circuit

Can be used with -bc and -bi to skip previous stages that already ran successfully. With --short-circuit, -bc starts directly at the build stage and -bi starts with the install stage.

--sign

Add a GPG signature to the package for verifying its integrity and origin.

--target platform

When building the package, set the macros %_target, %_target_arch, and %_target_os to the value indicated by platform.

Two other options can be used standalone with rpmbuild to recompile or rebuild a package:

--rebuild source-pkgfile...

Like --recompile, but also build a new binary package. Remove the build directory, the source files, and the spec file once the build is complete.

--recompile source-pkgfile...

Install the named source package, and prep, compile, and install the package.

Finally, the --showrc option is used to show the current rpmbuild configuration:

    rpmbuild --showrc

This option shows the values that will be used for all options that can be set in an rpmrc file.


Section 5.2. Yum: Yellowdog Updater Modified

5.2. Yum: Yellowdog Updater Modified

Yum is a system for managing RPM packages, including installing, updating, removing, and maintaining packages; it automatically handles dependencies between packages. Yum is derived from yup, an updating system written for Yellow Dog Linux, an RPM-based Macintosh distribution. Yum downloads the information in the package headers to a directory on your system, which it then uses to make decisions about what it needs to do. Yum obtains both the headers and the RPMs themselves from a collection of packages on a server, known as a repository.

A repository consists of a set of RPM packages and the package headers, which are on a server that can be accessed via FTP or HTTP, from an NFS server, or from a local filesystem. A single server can contain one or multiple repositories; repositories are often mirrored on many servers, and you can configure yum to use multiple repositories. When they are downloaded to your system, the header and package files are maintained in /var/cache/yum.

The configuration file, /etc/yum.conf, is where you customize yum. It consists of two section types. The first section, [main], sets configuration defaults for yum operation. This section is followed by [server] sections, where each server is named according to the repository it specifies. For example, for Fedora Core, you might have [base] for the base Fedora Core repository and [development] for the development repository.

The server sections can also be stored, one to a file, in /etc/yum.repos.d. yum comes with a default yum.conffile, which you can use as is or as a starting point from which to add additional repositories.

5.2.1. The yum Command

The yum command is an automated system for updating rpm-based packages, particularly on Fedora Core and Red Hat Enterprise Linux. Yum can automatically install, upgrade, and remove packages. In addition to individual packages or a list of packages, yum can operate on an entire group of packages at a time.

When you run yum, it first updates the cache (unless you tell it not to with the -C option); then it proceeds to perform the requested operation.

The format of the yum command is:

    yum [options] [command] [package ...]

Any general options are specified first, followed by a command telling yum what you want it to do, usually followed by a list of one or more packages. The command is always required, except with the --help, -h, and --version options.

Package names can be specified in various combinations of name, architecture, version, and release. For example, you could refer to the bash package as bash, bash.i386, bash-3.0, bash-3.0-17, or bash-3.0-17.i386.

5.2.1.1 General options

The following general options can be set on the command line. For those that can also be set in the [main] section of the yum.conf configuration file, the name of the configuration option is given.

-c [config-file]

Specify the location of the yum configuration file. The file can be specified as a path to a local file or as an HTTP or FTP URL. The default is /etc/yum.conf.

-C

Run entirely from the local cache. Don't download or update headers unless required to complete the requested action.

-d [num]

Set the debug level to num, which is generally a number between 0 and 10, to specify how much debugging information to print. The configuration option is debuglevel.

--disablerepo=repoid

Disable the repository specified by repoid so yum won't use it for this operation. The configuration option is enabled.

-e [num]

Set the error level to num, where num is a number, generally between 0 and 10. If the value is 0, print only critical errors. If it is 1, print all errors. Values greater than 1 mean print more errors, if there are any.

--enablerepo=repoid

Enable the specified repository that is marked as disabled (enable=0) in the configuration file. This allows the repository to be used for this operation. The configuration option is enabled.

--exclude=package

Exclude the specified package from updates on all repositories. package can be given as a name or a glob. The configuration option is exclude.

-h, --help

Display a help message and exit.

--installroot=root

Specify an alternative root for package installation. All packages will be installed relative to root. The configuration option is installroot.

--obsoletes

Enable obsoletes processing logic, taking into consideration packages that are obsoleted by other packages in the repository. Meaningful only with the yum update command. The configuration option is obsoletes.

-R [min]

Set the maximum amount of time in minutes that yum will wait before performing a command.

--rss-filename=filename

Use filename as the output file for the generate-rss command. The configuration option is rss-filename.

-t, --tolerant

Keep going (be tolerant) if there are package errors on the command line. This allows yum to continue processing other packages even if there is a problem with one package (e.g., trying to install a package that is already installed). The configuration option is tolerant.

-y

Assume that the answer to any question is yes. The configuration option is assumeyes.

5.2.2. Yum Command Summary

The individual yum commands are listed here.

check-update
check-update

Determine if updates are available, without running yum interactively. If any package updates are available, returns an exit value of 100 and a list of packages. If there are no updates, returns 0.

clean
clean [options]

Clean up the yum cache directory.

Options

all

Clean everything: headers, packages, metadata, and the cache.

cache

Clean up the cache.

headers

Remove all header files, forcing yum to download new headers the next time it runs.

metadata

Remove the metadata files, which maintain information about the packages such as package name, file size, description, dependencies, etc.

packages

Remove cached packages.

generate-rss
generate-rss [updates]

Create an rss file that lists changelogs for all packages in the enabled repositories. If updates is specified, the rss file lists only updates that apply to your system.

groupinfo
groupinfo groups

Like info, but operates on package groups instead of individual packages.

groupinstall
groupinstall groups

Like install, but operates on package groups instead of individual packages.

grouplist
grouplist

Generate a list of installed and available groups to standard output. You can use these groups as input parameters to the other group commands, with their names in quotes (" ").

groupremove
groupremove groups

Like remove, but operates on package groups instead of individual packages.

groupupdate
groupupdate groups

Like update, but operates on package groups instead of individual packages.

info
info [options] [packages]

Display version information, a summary, and a description for each package, or for all packages if none is specified. See the list command for a description of the options.

install
install packages

Install the latest version of a package or packages, ensuring that all dependencies are met. If no package matches the name as specified, the name is treated as a shell glob and any matches are installed.

list
list [options] [packages]

Display a list of packages that match the packages specification and that are installed or available for installation.

Options

all

List all installed or available packages.

available

List packages on the repository that are available for installation.

extras

List packages on the system that are not available on any repository in the configuration file.

installed

List installed packages.

obsoletes

List installed packages that are made obsolete by any packages in any repository in the configuration file.

updates

List packages that have updates available for installation.

localinstall
localinstall packages

Install the specified packages, which reside on the local system, rather than downloading them from a repository.

localupdate
localupdate packages

Update the specified packages, which reside on the local system, rather than downloading them from a repository.

makecache
makecache

Download and cache the metadata files from the repository. Once the cache has been built, you can use the -C option to run the commands that use the metadata (check-update, info, list, provides, and search) directly from the cache.

provides
provides feature1 [feature2 ...]
whatprovides feature1 [feature2 ...]

List packages that are available or installed that provide the specified features. The features can be specified as a name or as a wildcard in file-glob syntax format, and Perl or Python regular expressions can be used.

remove
remove package1 [package2 ...]
erase package1 [package2 ...]

Remove the specified packages from the system. Also remove any packages that depend on the specified packages.

search
search string1 [string2 ...]

Find packages matching the specified string or strings in the description, summary, packager, or package name fields. Perl or Python regular expressions can be used for the strings. Useful for finding a package if you don't know the name.

update
update [packages]

With no packages specified, update all installed packages. Otherwise, update the specified packages. In either case, yum makes sure that all dependencies are satisfied. If no package matches, the names specified are assumed to be shell globs, and any matches are installed.

With the --obsoletes option, yum includes package obsoletes in its calculations.

upgrade
upgrade [packages]

Equivalent to update --obsoletes.


Section 5.3. up2date: Red Hat Update Agent

5.3. up2date: Red Hat Update Agent

The Red Hat Update Agent, up2date, installs and updates packages on RPM-based systems, primarily on Red Hat and Fedora Core Linux systems. Originally, up2date was intended for use with Red Hat Enterprise Linux and the Red Hat Network, but it has since been updated to work with yum and apt repositories as well. up2date operates on groupings of packages known as channels, based on the system architecture and Fedora Core or Red Hat Enterprise release. For example, a channel might be fedora-core-3, containing packages for that distribution; this type of channel is a base channel. Child channels are associated with a base channel and contain extra packages, such as for an application or a set of applications. Entries for the channels are found in /etc/sysconfig/rhn/sources. This file contains an entry for each channel that associates the repository type (e.g., up2date, yum, or apt) with a channel name, and a URL in the case of a yum repository. For an apt repository, the URL is separated by spaces into parts: service:server, path, and repository name. You can also include entries for a local directory of packages, known as a dir repository.

up2date has both a command-line and a graphical interface; it is primarily the command-line interface that we describe in this section. If you are running GNOME or KDE and have the rhn-applet installed, clicking on the icon in the panel brings up the graphical up2date interface. The rhn-applet is the Red Hat Network Notification Tool, which runs in your desktop panel and notifies you when package updates are available. The panel icon is red with a blinking exclamation point if updates are available, and blue with a check mark if your system is up to date.

The format of the up2date command is:

    up2date [options] [packages]

There are two additional commands:

    up2date-nox [options] [packages]
    up2date-config

Running up2date-nox is equivalent to running up2date with the --nox option; it runs without X (without the graphical interface). up2date-config runs a graphical tool for configuring up2date. You can also configure the program by editing the configuration file, /etc/sysconfig/rhn/up2date, directly. These versions of the up2date command are not described further here.

Running up2date with no packages specified brings up the graphical interface. With packages, up2date updates or installs those packages, resolving dependencies as needed. Specify packages by name; up2date determines the appropriate version, release, and distribution.

5.3.1.

5.3.1.1 Options

--arch=arch

Install the package for the specified architecture. Not valid with -u, --list, or --dry-run.

--configure

Configure the Update Agent. Puts up a graphical window that lets you configure proxy and authentication information, retrieval options, and packages and files to skip.

--channelchannels

Specify the channels to use.

-d, --download

Download the specified package, but do not install it.

--dbpathpath

Specify the path to an alternate RPM database. The default path is /var/lib/rpm.

--dry-run

Go through the motions, but don't actually download and install any packages.

--excludepackages

Exclude packages in the comma-separated list of packages from being installed or updated.

-f, --force

Force package installation. Override file, package, and configuration skip lists.

--get

Download the packages, but don't resolve any dependencies.

--get-source

Download the source package. Don't resolve any dependencies.

--gpg-flags

List the flags that will be used when GPG is invoked. Useful for scripts that want to invoke GPG the way up2date does.

-h, --help

Print a help message and exit.

-i, --install

Download and install the package. Override configuration option. Cannot be used with --download.

--installall

Install all available packages on the channel specified by --channel.

--justdb

Add packages to the database, but do not install them to the filesystem.

-k, --packagedirdirs

Use the colon-separated list of directories to search for packages.

-l,--list

List packages available for update. Also shows packages marked to be skipped.

--list-rollbacks

Display a list of all RPM rollbacks available. A rollback lets you return to an earlier state before you installed a package.

--nodownload

Do not download any packages. Used for testing.

--nosig

Do not use GPG to check package signatures. If specified, overrides configuration option.

--nosrc

Do not download source packages. If specified, overrides configuration option.

--nox

Do not display the graphical interface.

--proxyproxy

Specify an HTTP proxy to use.

--proxyUser=username

Specify the username to use with an authenticated HTTP proxy.

--proxyPassword=password

Specify a password to use with an authenticated HTTP proxy.

--register

Register or reregister the system.

--showall

Display a list of all packages available for download, including both packages that are already installed and those that are not.

--show-available

Display a list of all packages available for download and not currently installed.

--show-channels

Show the channels associated with a package. If used alone, show the currently subscribed channels.

--show-groups

Display a list of package groups that are available for download.

--show-orphans

List any installed packages that are not in any of the subscribed-to channels.

--show-package-dialog

When running in GUI mode, show the package installation dialog.

--solve-deps=dependencies

Download and install packages needed to resolve the specified dependencies. The dependencies are given in a comma-separated list.

--src

Download source, as well as binary, RPMs.

--serverUrl=url

Specify the URL of the server to use.

--tmpdir=directory

Specify a temporary storage directory for files and packages, overriding the configured value.

-u, --update

Do a complete system update, downloading and installing all relevant packages.

--undo

Undo the last package set update.

--upgrade-to-release=release-version

Upgrade to the specified release, where release-version indicates the channel for that release.

-v, --verbose

Display additional output.

--version

Print version information and exit.

--what-provides=dependencies

List packages that solve the comma-separated list of dependencies.


Section 5.4. The Debian Package Manager

5.4. The Debian Package Manager

Debian GNU/Linux provides several package-management tools, primarily intended to facilitate the building, installation, and management of binary packages. In addition to Debian GNU/Linux, the tools described here also work on other Debian-based systems such as Xandros, Knoppix, Ubuntu, and numerous others.

Debian package names generally end in .deb. The Debian package-management tools described here include apt, aptitude, dpkg, dpkg-deb, dselect, and synaptic.

Each of these tools is described later in detail in Debian Package Manager Command Summary.."

5.4.1. Files

Some important files used by the Debian package-management tools are describied briefly here:

control

Comes with each package. Documents dependencies; contains the name and version of the package, a description, maintainer, installed size, the package priority, etc.

conffiles

Comes with each package. Contains a list of the configuration files associated with the package.

preinst, postinst, prerm, postrm

Scripts developers can include in a package to be run before installation, after installation, before removal, or after removal of the package.

/var/lib/dpkg/available

Contains information about packages available on the system.

/var/lib/dpkg/status

Contains information about the status of packages available on the system.

/etc/apt/sources.list

A list for APT of package sources, used to locate packages. The sources are listed one per line, in order of preference.

/etc/apt/apt.conf

The main APT configuration file.

/etc/apt/apt_preferences

A preferences file that controls various aspects of APT, such as letting a user select the version or release of a package to install.

/etc/dpkg/dpkg.cfg

A configuration file containing default options for dpkg.

For a user, the important file is /etc/apt/sources.list. This file is where you set up the paths to the package archives, telling apt where to go to find packages. apt is installed with a default file. You aren't required to modify the sources in the file, but you'll probably want to change some sources or add additional ones at some point. You might also want to change some of the options in the configuration files apt.conf, apt_preferences, and dpkg.config if you aren't satisfied with the defaults. The control, conffiles, and the pre- and post- install and removal script files are created by the package developers and used internally by the package-management system.

5.4.2. Package Priorities

Every Debian package has a priority associated with it, indicating how important the package is to the system. The priorities are:

required

The package is essential to the proper functioning of the system.

important

The package provides important functionality that enables the system to run well.

standard

The package is included in a standard system installation.

optional

The package is one that you might want to install, but you can omit it if you are short on disk space, for example.

extra

The package either conflicts with other packages that have a higher priority, has specialized requirements, or is one that you would want to install only if you need it.

The control file for dpkg, for example, shows that dpkg itself has a priority of required; dpkg-dev (which provides tools for building Debian packages) has a priority of standard; and dpkg-doc is optional.

5.4.3. Package and Selection States

The possible states that a package can be in are:

config-files

Only the configuration files for the package are present on the system.

half-configured

The package is unpacked, and configuration was started but not completed.

half-installed

Installation was started but not completed.

installed

The package is unpacked and configured.

not-installed

The package is not installed.

unpacked

The package is unpacked but not configured.

The possible package selection states are:

deinstall

The package has been selected for deinstallation (i.e., for removal of everything but the configuration files).

install

The package has been selected for installation.

purge

The package has been selected to be purged (i.e., for removal of everything including the configuration files).

5.4.4. Package Flags

Two possible package flags can be set for a package:

hold

The package should not be handled by dpkg unless forced with the --force-hold option. Holding a package keeps it at the current version, preventing it from being updated. You might hold a package, for example, if the latest version is broken and you want to stay with the version you have until a newer one is released.

reinst-required

The package is broken and needs to be reinstalled. Such a package cannot be removed unless forced with the --force-reinstreq option.

5.4.5. Scripts

In addition to the commands described in the next section, a number of shell and Perl scripts are included with the package manager for use in managing and building packages:

apt-file

Search for packages, specifying an action and a pattern to search for. (Perl script)

apt-rdepends

Recursively list dependencies. (Perl script)

apt-setup

An interactive script for adding download sources to the sources.list file. (Shell script)

dpkg-architecture

Determine and set the build and host architecture for package building. (Perl script)

dpkg-checkbuilddeps

Check installed packages against the build dependencies and build conflicts listed in the control file. (Perl script)

dpkg-buildpackage

A control script to help automate package building. (Shell script)

dpkg-distaddfile

Add an entry for a file to debian/files. (Perl script)

dpkg-divert

Create and manage the list of diversions, used to override the default location for installing files. (Perl script)

dpkg-genchanges

Generate an upload control file from the information in an unpacked, built source tree and the files it has generated. (Perl script)

dpkg-gencontrol

Read information from an unpacked source tree, generate a binary package control file (by default, debian/tmp/DEBIAN/control), and add an entry for the binary file to debian/files. (Perl script)

dpkg-name

Rename Debian packages to their full package names. (Shell script)

dpkg-parsechangelog

Read and parse the changelog from an unpacked source tree and write the information to standard output in machine-readable form. (Perl script)

dpkg-preconfigure

Let packages ask questions prior to installation. (Perl script)

dpkg-reconfigure

Reconfigure a package that is already installed. (Perl script)

dpkg-scanpackages

Create a Packages file from a tree of binary packages. The Packages file is used by dselect to provide a list of packages available for installation. (Perl script)

dpkg-shlibdeps

Calculate shared library dependencies for named executables. (Perl script)

dpkg-source

Pack and unpack Debian source archives. (Perl script)

dpkg-statoverride

Manage the list of stat overrides, which let dpkg override file ownership and mode when a package is installed. (Perl script)

5.4.6. Debian Package Manager Command Summary

For the apt- commands, options can be specified on the command line or set in the configuration file. Boolean options set in the configuration file can be overridden on the command line in a number of different ways, such as --no-opt and -opt=no, where opt is the single-character or full name of the option.

apt-cache
apt-cache [options] command

Perform low-level operations on the APT binary cache, including the ability to perform searches and produce output reports from package metadata.

Commands

add files

Add the specified package index files to the source cache.

depends pkgs

For each specified package, show a list of dependencies and packages that can fulfill them.

dotty pkgs

Graph the relationships between the specified packages. The default is to trace out all dependent packages; turn this behavior off by setting the APT::Cache::GivenOnly configuration option.

dump

List every package in the cache. Used for debugging.

dumpavail

Print a list of available packages to standard output, suitable for use with dpkg.

gencaches

Build source and package caches from the sources in the file sources.list and from /var/lib/dpkg/status. Equivalent to running apt-get check.

madison [pkgs]

Display a table showing the available versions of each specified package. Similar to madison, a Debian tool that checks for package versions and reports their status. This option works locally and doesn't require access to the Debian project's internal archive.

pkgnames [prefix]

Print a list of packages in the system. If prefix is specified, print only packages whose names begin with that prefix. Most useful with the --generate option.

policy [pkgs]

Print detailed information about the priority selection of each specified package. With no arguments, print the priorities of all sources. Useful for debugging issues related to the preferences file.

rdepends [pkgs]

Show a list of reverse dependencies for each specified packagei.e., list any packages that depend on the specified packages.

search regex

Search package names and descriptions of all available package files for the specified regular expression and print the name and short description of each matching package. With --full, the output is identical to that from the show command. With --names-only, only the package name is searched. Multiple regular expressions can be specified. Useful for finding packages when you don't know the actual package name.

show pkgs

Display the package records for each specified package. See the -a option for more details.

showpkg pkgs

Display information about the specified packages. For each package, the output includes the available versions, packages that depend on this package, and packages that this package depends on. Useful for debugging.

showsrc pkgs

Display source package records for each specified package.

stats

Display statistics about the cache.

unmet

Display the unmet dependencies in the package cache.

Options

-a, --all-versions

Print full records for all available versions. For use with the show command. The default is to show all versions; turn it off with --no-all-versions to display only the version that would be installed. The configuration option is APT::Cache::AllVersions.

--all-names

Cause pkgnames to print all names, including virtual packages and missing dependencies. The configuration option is APT::Cache::AllNames.

-c file, --config-file=file

Specify a configuration file to be read after the default configuration file.

-f, --full

Print full package records when searching. The configuration option is APT::Cache::ShowFull.

-g, --generate

Automatically regenerate the package cache rather than using the current cache. Default is to regenerate; turn it off with --no-generate. The configuration option is APT::Cache::Generate.

-h, --help

Print usage information and exit.

-i, --important

Print only important dependencies (Depends and Pre-Depends relations). For use with unmet. The configuration option is APT::Cache::Important.

--installed

Only produce output for currently installed packages. For use with depends and rdepends. The configuration option is APT::Cache::Installed.

-n, --names-only

Search only on package names, not long descriptions. The configuration option is APT::Cache::NamesOnly.

-o, --option

Set a configuration option. Syntax is -o group::tool=option.

-p file, --pkg-cache=file

Use the specified file for the package cache, the primary cache used by all operations. The configuration option is Dir::Cache::pkgcache.

-q, --quiet

Operate quietly, producing output for logging but no progress indicators. Use -qq for even quieter operation. The configuration option is quiet.

--recurse

Run depends or rdepends recursively, so all specified packages are printed once. The configuration option is APT::Cache::RecurseDepends.

-s file, --src-cache=file

Specify the source cache file used by gencaches. The configuration option is Dir::Cache::srcpkgcache.

-v, --version

Print version information and exit.

apt-cdrom
apt-cdrom [options] command

Add a new CD-ROM to APT's list of available sources. The database of CD-ROM IDs that APT maintains is /var/lib/apt/cdroms.list.

Commands

add

Add a CD-ROM to the source list.

ident

Print the identity of the current CD-ROM and the stored filename. Used for debugging.

Options

-a, --thorough

Do a thorough package scan. May be needed with some old Debian CD-ROMs.

-c file, --config-file=file

Specify a configuration file to be read after the default configuration file.

-d mount-point, --cdrom=mount-point

Specify the CD-ROM mount point, which must be listed in /etc/fstab. The configuration option is Acquire::cdrom::mount.

-f, --fast

Do a fast copy, assuming the files are valid and don't all need checking. Specify this only if the disk has been run before without error. The configuration option is APT::CDROM::Fast.

-h, --help

Print help message and exit.

-m, --no-mount

Don't mount or unmount the mount point. The configuration option is APT::CDROM::NoMount.

-n, --just-print, --recon, --no-act

Check everything, but don't actually make any changes. The configuration option is APT::CDROM::NoAct.

-o, --option

Set a configuration option. Syntax is -o group::tool=option.

-r, --rename

Prompt for a new label and rename the disk to the new value. The configuration option is APT::CDROM::Rename.

-v, --version

Print the version information and exit.

apt-config
apt-config [options] shell args
apt-config [options] dump

An internal program for querying configuration information.

Commands

dump

Display the contents of the configuration space.

shell

Access the configuration information from a shell script. The arguments are in pairs, specifying the name of a shell variable and a configuration value to query. The value may be postfixed with /x, where x is one of the following letters:

b

Return true or false.

d

Return directories.

f

Return filenames.

i

Return an integer.

Options

-c file, --config-file=file

Specify a configuration file to be read after the default configuration file.

-h, --help

Print help message and exit.

-o, --option

Set a configuration option. Syntax is -o group::tool=option.

-v, --version

Print the version information and exit.

apt-extract-templates
apt-extracttemplates [options] files

Extract configuration scripts and templates from the specified Debian package files. For each specified file, a line of output is generated with the following information:

package version template-file config-script

and the template files and configuration scripts are written to the directory specified with -t or --temp-dir, or by the configuration option APT::ExtractTemplates::TempDir. The filenames are in the form package.template.xxxx and package.config.xxxx.

Options

-c file, --config-file=file

Specify a configuration file to be read after the default configuration file.

-h, --help

Print help message and exit.

-o, --option

Set a configuration option. Syntax is -o group::tool=option.

-t dir, --tempdir=dir

Write the extracted template files and configuration scripts to the specified directory. The configuration option is APT::ExtractTemplates::TempDir.

-v, --version

Print the version information and exit.

apt-ftparchive
apt-ftparchive [options] command

Generate package and other index files used to access a distribution source. The files should be generated on the source's origin site.

Commands

clean config-file

Clean the databases used by the specified configuration file by removing obsolete records.

contents path

Search the specified directory tree recursively. For each .deb file found, read the file list, sort the files by package, and write the results to standard output. Use with --db to specify a binary caching database.

generate config-file sections

Build indexes according to the specified configuration file.

packages path [override [pathprefix]]

Generate a package file from the specified directory tree. The optional override file contains information describing how the package fits into the distribution, and the optional path prefix is a string prepended to the filename fields. Similar to dpkg-scanpackages. Use with --db to specify a binary caching database.

release path

Generate a release file from the specified directory tree.

sources paths [override [pathprefix]]

Generate a source index file from the specified directory tree. The optional override file contains information used to set priorities in the index file and to modify maintainer information. The optional path prefix is a string prepended to the directory field in the generated source index. Use --source-override to specify a different source override file. Similar to dpkg-scansources.

Options

-c file, --config-file=file

Specify a configuration file to be read after the default configuration file.

--contents

Perform contents generation. If set and if package indexes are being generated with a cache database, the file listing is extracted and stored in the database. If used with generate, allows the creation of any contents files. The default is on. The configuration option is APT::FTPArchive::Contents.

-d, --db

Use a binary caching database. This option has no effect on generate. The configuration option is APT::FTPArchive::DB.

--delink

Enable delinking of files when used with the External-Links setting. The default is on; turn off with --no-delink. The configuration option is APT::FTPArchive::DeLinkAct.

-h, --help

Print help message and exit.

--md5

Generate MD5 sums for the index files. The default is on. The configuration option is APT::FTPArchive::MD5.

-o, --option

Set a configuration option. Syntax is -o group::tool=option.

-q, --quiet

Run quietly, producing logging information but no progress indicators. Use -qq for quieter operation. The configuration option is quiet.

--read-only

Make the caching databases read-only. The configuration option is APT::FTPArchive::ReadOnlyDB.

-s file, --source-override=file

Specify a source override file. Use with the sources command. See the sources command description for more information. The configuration option is APT::FTPArchive::SourceOverride.

-v, --version

Print the version information and exit.

apt-get
apt-get [options] command [package...]

A command-line tool for handling packages. Also serves as a backend to other APT tools such as dselect, synaptic, and aptitude (all described later in this section). As described earlier in this chapter, the following command can be run every day to keep your system updated:

apt-get update && apt-get -u dist-upgrade

Commands

autoclean

Like clean, but remove only package files that can no longer be downloaded. Set the configuration option APT::Clean-Installed to off to prevent installed packages from being erased

build-dep

Install or remove packages to satisfy the build dependencies for a source package.

clean

Clear the local repository of retrieved package files. Useful for freeing up disk space.

check

Update the package cache and check for broken packages.

dist-upgrade

Like upgrade, but also handle dependencies intelligently. See the -f option for more information.

dselect-upgrade

Used with dselect. Track the changes made by dselect to the Status field of available packages and take actions necessary to realize that status.

install packages

Install one or more packages. Specify the package name, not the full filename. Other required packages are also retrieved and installed. With a hyphen appended to the package name, the package is removed if it is already installed. Select a version to install by appending an equals sign and the version.

remove packages

Remove one or more packages. Specify the package name, not the full filename. With a plus sign appended to the name, the package is installed.

source packages

Find source packages and download them into the current directory. If specified with --compile, the source packages are compiled into binary packages. With --download-only, the source packages are not unpacked. Select a specific version by appending an equals sign and the version.

update

Resynchronize the package overview files from their sources. Must be done before an upgrade or dist-upgrade.

upgrade

Install the latest versions of all packages currently installed. Run update first.

Options

--arch-only

Process only architecture-dependent build dependencies. Configuration option is APT::Get::Arch-Only.

-b, --compile, --build

Compile source packages after download. The configuration option is APT::Get::Compile.

-c file, --config-file=file

Specify a configuration file to read after the default.

-d, --download-only

Retrieve package files, but don't unpack or install them. The configuration option is APT::Get::Download-only.

--diff-only

Download only the diff file from a source archive. The configuration option is APT::Get::Diff-Only.

-f, --fix-broken

Try to fix a system with broken dependencies. Can be used alone or with a command. Run with the install command if you have problems installing packages. You can run the sequence:

    apt-get -f install

    apt-get dist-upgrade

several times to clean up interlocking dependency problems. The configuration option is APT::Get::Fix-Broken.

--force-yes

Force yes. Cause APT to continue without prompting if it is doing something that could damage your system. Use with great caution and only if absolutely necessary. The configuration option is APT::Get::force-yes.

-h, --help

Display a help message and exit.

--ignore-hold

Ignore a hold placed on a package, which would normally prevent the package frorm being upgraded. Use with dist-upgrade to override many undesired holds. The configuration option is APT::Get::Ignore-Hold.

--list-cleanup

Erase obsolete files from /var/lib/apt/lists. The default is on; use --no-list-cleanup to turn it off, which you would normally do only if you frequently modify your list of sources. The configuration option is APT::Get::List-Cleanup.

-m, --ignore-missing, --fix-missing

Ignore missing or corrupted packages or packages that cannot be retrieved. Can cause problems when used with -f. The configuration option is APT::Get::Fix-Missing.

--no-download

Disable package downloading; use with --ignore-missing to force APT to use only the packages that have already been downloaded. The configuration option is APT::Get::Download.

--no-remove

Do not remove any packages; instead, abort without prompting. The configuration option is APT::Get::Remove.

--no-upgrade

Do not upgrade packages. Use with install to prevent upgrade of packages that are already installed. The configuration option is APT::Get::Upgrade.

-o, --option

Set a configuration option. Syntax is -o group::tool=option.

--only-source

Do not map the names specified with the source or build-dep commands through the binary table. With this option, only source package names can be specified. The configuration option is APT::Get::Only-Source.

--print-uris

Print Uniform Resource Indicators (URIs) of files instead of fetching them. Print path, destination filename, size, and expected MD5 hash. The configuration option is APT::Get::Print-URIs.

--purge

Tell dpkg to do a purge instead of a remove for items that would be removed. Purging removes packages completely, including any configuration files. The configuration option is APT::Get::Purge.

-q, --quiet

Quiet mode. Omit progress indicators and produce only logging output. Use -qq to make even quieter. The configuration option is quiet.

--reinstall

Reinstall packages that are already installed, upgrading them to the latest version. The configuration option is APT::Get::ReInstall.

-s, --simulate, --just-print, --dry-run, --recon, --no-act

Go through the motions, but don't actually make any changes to the system. The configuration option is APT::Get::Simulate.

-t rel, --target-release=rel, --default-release=rel

Retrieve packages only from the specified release. The value of rel can be a release number or a value such as "unstable." The configuration option is APT::Default-Release.

--tar-only

Download only the tar file from a source archive. The configuration option is APT::Get::Tar-Only.

--trivial-only

Perform only operations that are considered triviali.e., ones that won't harm your system, by, say, removing needed files. Unlike --assume-yes, which always answers "yes" to any prompts, --trivial-only always answers "no." The configuration option is APT::Get::Trivial-Only.

-u, --show-upgraded

Print a list of all packages to be upgraded. The configuration option is APT::Get::Show-Upgraded.

-v, --version

Display the version and exit.

-V, --verbose-versions

Show full versions for upgraded and installed packages. The configuration option is APT::Get::Show-Versions.

-y, --yes, --assume-yes

Automatically reply "yes" to prompts and run noninteractively. Abort if there is an error. The configuration option is APT::Get::Assume-Yes.

apt-sortpkgs
apt-sortpkgs [options] indexfiles

Sort the records in a source or package index file by package name and write the results to standard output. apt-sortpkgs also sorts the internal fields of each record.

Options

-c file, --config-file=file

Specify a configuration file to read after the default.

-h, --help

Display a help message and exit.

-o, --option

Set a configuration option. Syntax is -o group::tool=option.

-s, --source

Order by source index field. The configuration option is APT::SortPkgs::Source.

-v, --version

Display the version and exit.

aptitude
aptitude [options] [action[arguments]]

A text-based frontend to apt, which can be run either directly from the command line or from a visual mode that runs in a terminal window.

Actions

The following actions are supported. Running aptitude with no action invokes the visual mode. Package names can be entered individually or as search patterns. A search pattern consists of terms starting with a tilde (~), followed by a character indicating the type of term, followed by the text to be searched for. The most common usage is to use ~n to search for a package name (e.g., ~nemacs, to search for packages that have emacs in their name). You can find the full list of term types in the Aptitude User's Manual. The manual can be found in /usr/share/doc/READMEon a Debian system. On an RPM-based system with aptitude installed, the README file may be in /usr/share/aptitude or /usr/share/doc/aptitude.

autoclean

Clean out the cache by removing only packages that can no longer be downloaded.

clean

Clean out the cache by removing all previously downloaded .deb files.

dist-upgrade

Upgrade as many installed packages as possible, installing and removing packages as needed to satisfy dependencies.

download packages

Download the .deb file for each specified package to the current directory.

forbid-version package[=version]...

Don't allow aptitude to upgrade the package to a particular version. If no version is specified, it is assumed to be the version that would normally be used.

forget-new

Remove internal information about what packages are "new."

help

Display help information and exit.

hold packages

Place a hold on each specified package.

install [package[=version] ...]

Install the specified packages. With a version, install that version. With no arguments, install any stored or pending actions. You can also use install to perform different actions on multiple packages with a single command. Append - to the package name to remove, + to install, _ to purge, or = to hold a package.

markauto packages

Mark the specified packages as automatically installed.

purge [package[=version] ...]

Remove the specified packages and their configuration files.

remove [package[=version] ...]

Remove the specified packages.

search patterns

Search for packages matching each of the specified patterns and display a list of matches. The full list of search terms can be found in the Aptitude User's Manual.

show patterns

Search for packages matching each of the specified patterns and display detailed information for every match found.

unhold packages

Remove the hold on each specified package.

unmarkauto packages

Mark the specified packages as manually installed.

update

Update the list of available packages by downloading the names of new and upgradeable packages.

upgrade

Upgrade as many packages as possible; if a package has dependency problems, avoid upgrading that package (but don't remove it).

Options

Most of the aptitude options have corresponding configuration options that can be set in the configuration file.

-d, --download-only

Download packages to the cache but do not install them. Configuration option is Aptitude::CmdLine::Download-Only.

-D, --show-deps

Show summaries of why packages will be automatically installed or removed. Configuration option is Aptitude::CmdLine::Show-Deps.

-f

Attempt to fix dependencies of broken packages. Configuration option is Aptitude::CmdLine::Fix-Broken.

-F format, --display-format format

Specify the output format for search. See the Aptitude User's Manual for details on specifying the format. Configuration option is Aptitude::CmdLine::Package-Display-Format.

-h, --help

Print help message and exit.

-O order, --sort order

Specify the sort order for search output. See the Aptitude User's Manual for details.

-P,--prompt

Always display a prompt even for actions that were explicitly requested. The corresponding configuration option is Aptitude::CmdLine::Always-Prompt.

-r, --with-recommends

Treat recommendations as dependencies when installing new packages. The corresponding configuration option is Aptitude::CmdLine::Recommends-Important.

-R, --without-recommends

Do not treat recommendations as dependencies when installing new packages. The corresponding configuration option is Aptitude::CmdLine::Recommends-Important.

-s, --simulate

Go through the motions, but do not actually perform the actions. Print the actions that would be performed. Configuration option is Aptitude::CmdLine::Simulate.

-t release, --target-release release

Specify the release to use for installing packages. Configuration option is Aptitude::CmdLine::Default-Release.

-v, --verbose

Operate verbosely, displaying additional information. Specify multiple times to get even more information displayed. Configuration option is Aptitude::CmdLine::Verbose.

-V, --show-versions

Display the version for packages being installed. Configuration option is Aptitude::CmdLine::Show-Versions.

--version

Display the version information for aptitude and exit.

--visual-preview

Start the visual interface and display the preview screen.

-w width, --width width

Specify the output display width for search. The default is the terminal width. The corresponding configuration option is Aptitude::CmdLine::Package-Display-Width.

-y, --assume-yes

Assume a yes response to a yes/no prompt and don't display the prompt. Prompts for dangerous actions are still shown. This option overrides -P. The corresponding configuration option is Aptitude::CmdLine::Assume-Yes.

-Z

Display the disk space that will be used or freed by the packages being acted upon. The corresponding configuration option is Aptitude::CmdLine::Show-Size-Changes.

Internal options

The following options are used internally for aptitude's visual mode. You shouldn't need to issue them directly.

-i

Display a download preview when the program starts. Cannot be used with -u.

-S filename

Load extended state information from the specified file, not the default state file.

-u

Begin updating the package lists as soon as the program starts. Cannot be used with -i.

dpkg
dpkg [options] action

A tool for installing, managing, and building packages. Also serves as a frontend to dpkg-deb and dpkg-query.

dpkg actions

These actions are carried out by dpkg itself:

-A pkgfile, --record-avail pkgfile

Update the record of available files kept in /var/lib/dpkg/available with information from pkgfile. This information is used by dpkg and dselect to determine which packages are available. With -R or --recursive, pkgfile must be a directory.

-C, --audit

Search for partially installed packages and suggest how to get them working.

--clear-avail

Remove existing information about which packages are available.

--command-fd n

Accept commands passed on the file descriptor given by n. Note that any additional options set through this file descriptor or on the command line are not reset, but remain for other commands issued during the same session.

--compare-versions ver1 op ver2

Perform a binary comparison of two version numbers. The operators lt le eq ne ge gt treat a missing version as earlier. The operators lt-nl le-nl ge-nl gt-nl treat a missing version as later (where nl is "not later"). A third set of operators (< << <= = >= >> >) is provided for compatibility with control-file syntax. dpkg returns zero for success (i.e., the condition is satisfied) and nonzero otherwise.

--configure [packages|-a|--pending]

Reconfigure one or more unpacked packages. If -a or --pending is given instead of packages, configure all packages that are unpacked but not configured. Configuring a package involves unpacking the configuration files, backing up the old configuration files, and running the postinst script if one is present.

-Dh, --debug=help

Print debugging help message and exit.

--force-help

Print help message about the --force-list options and exit. See the --force- list option description for the possible values of list.

--forget-old-unavail

Forget about uninstalled, unavailable packages.

--get-selections [pattern]

Get list of package selections and write to standard output. With pattern specified, write selections that match the pattern.

--help

Print help message and exit.

-i pkgfile, --install pkgfile

Install the package specified as pkgfile. With -R or --recursive, pkgfile must be a directory.

--license, --licence

Print dpkg license information and exit.

--print-architecture

Print the target architecture.

--print-gnu-build-architecture

Print the GNU version of the target architecture.

--print-installation-architecture

Print the host architecture for installation.

-r, --remove [packages|-a|--pending]

--purge [packages|-a|--pending]

Remove or purge one or more installed packages. Removal gets rid of everything except the configuration files listed in debian/conffiles; purging also removes the configuration files. If -a or --pending is given instead of packages, dpkg removes or purges all packages that are unpacked and marked (in /var/lib/dpkg/status) for removing or purging.

--set-selections

Set package selections based on input file read from standard input.

--unpack pkgfile

Unpack the package, but don't configure it. When used with -R or --recursive, pkgfile must be a directory.

--update-avail pkgs-file

--merge-avail pkgs-file

Update the record of available files kept in /var/lib/dpkg/available. This information is used by dpkg and dselect to determine what packages are available. Update replaces the information with the contents of the pkgs-file, distributed as Packages. Merge combines the information from Packages with the existing information.

--version

Print dpkg version information and exit.

--yet-to-unpack

Search for uninstalled packages that have been selected for installation.

dpkg-deb actions

The following actions can be specified for dpkg and are passed to dpkg-deb for execution. Also see dpkg-deb.

-b dir [archive], --build dir [archive]

Build a package.

-c archive, --contents archive

List the contents of a package.

-e archive [dir], --control archive [dir]

Extract control information from a package.

-f archive [control-fields], --field archive [control-fields]

Display the control field or fields of a package.

-I archive [control-files], --info archive [control-files]

Show information about a package.

--fsys-tarfile archive

Write the filesystem tree contained in a package to standard output in tar format.

-x archive dir, --extract archive dir

Extract the files from a package.

-X archive dir, --vextract archive dir

Extract the files and display the filenames from a package.

dpkg-query actions

The following actions can be specified for dpkg and are passed to dpkg-query for execution. Also see dpkg-query.

-l, --list [pkg-name-pattern]

List all packages whose names match the specified pattern. With no pattern, list all packages in /var/lib/dpkg/available. The pattern can include standard shell wildcard characters and may have to be quoted to prevent the shell from doing filename expansion.

-L packages, --listfiles packages

List installed files that came from the specified package or packages.

-p, --print-avail package

Print the details about package from /var/lib/dpkg/available.

-s packages, --status packages

Report the status of one or more packages by displaying the entry in the status database /var/lib/dpkg/status.

-S filename-pattern, --search filename-pattern

Search installed packages for a filename. The pattern can include standard shell wildcard characters and may have to be quoted to prevent the shell from doing filename expansion.

Options

dpkg options can be specified on the command line or set in the configuration file. Each line in the configuration file contains a single option, specified without the leading dash (-).

--abort-after=num

Abort processing after num errors. Default is 50.

--admindir= dir, --instdir= dir, --root=dir

Change default directories. admindir contains administrative files with status and other information about packages; it defaults to /var/lib/dpkg. instdir is the directory into which packages are installed; it defaults to /. Changing the root directory to dir automatically changes instdir to dir and admindir to /dir/var/lib/dpkg.

-B, --auto-deconfigure

When a package is removed, automatically deconfigure any other package that depended on it.

-Doctal, --debug=octal

Turn on debugging, with the octal value specifying the desired level of debugging information. Use -Dh or --debug=help to display the possible values. You can OR the values to get the desired output.

-E, --skip-same-version

Don't install the package if this version is already installed.

--force-list, --no-force-list, --refuse-list

Force or refuse to force an operation. list is specified as a comma-separated list of options. With --force, a warning is printed, but processing continues. --refuse and --no-force cause processing to stop with an error. Use --force-help to display a message describing the options. The force/refuse options are:

all

Turn all force options on or off.

architecture

Process even if intended for a different architecture.

auto-select

Select or deselect packages to install or remove them. Forced by default.

bad-path

Some programs are missing from the path.

bad-verify

Install package even if it fails to verify.

confdef

Always choose the default action for modified configuration files. If there is no default and confnew or confold is also specified, use that to decide; otherwise, ask the user.

configure-any

Configure any unconfigured package that the package depends on.

conflicts

Permit installation of conflicting packages. Can result in problems from files being overwritten.

confmiss

Always install a missing configuration file. Be careful using this option, since it means overriding the removal of the file.

confnew

Always install the new version of a modified configuration file, unless confdef is also specified. In that case, use the default action if there is one.

confold

Keep the old version of a modified configuration file, unless confdef is also specified. In that case, use the default action if there is one.

depends

Turn dependency problems into warnings.

depends-version

Warn of version problems when checking dependencies, but otherwise ignore.

downgrade

Install even if a newer version is already installed. Forced by default.

hold

Process packages even if they are marked to be held.

not-root

Try to install or remove even when not logged on as root.

overwrite

Overwrite a file from one package with the same file from another package.

overwrite-dir

Overwrite one package's directory with a file from another package.

overwrite-diverted

Overwrite a diverted file with an undiverted version.

remove-essential

Remove a package even if it is essential. Note that this can cause your system to stop working.

remove-reinstreq

Remove a package even if it is broken and is marked to require reinstallation.

-G

Don't install a package if a newer version is already installed. Same as --refuse-downgrade.

--ignore-depends=pkglist

Dependency problems result only in a warning for the packages in pkglist.

--new

New binary package format. This is a dpkg-deb option.

--no-act,--dry-run,--simulate

Go through the motions, but don't actually write any changes. Used for testing. Be sure to specify before the action; otherwise, changes might be written.

--nocheck

Ignore the contents of the control file when building a package. This is a dpkg-deb option.

-O, --selected-only

Process only packages that are marked as selected for installation.

--old

Old binary package format. This is a dpkg-deb option.

-R, --recursive

Recursively handle .deb files found in the directories and their subdirectories specified with -A, -i, --install, --unpack, and --avail.

--status-fd n

Send the package status information to the specified file descriptor. Can be given more than once.

dpkg-deb
dpkg-deb action [options]

Backend command for building and managing Debian package archives. Also see dpkg; you'll often want to use dpkg to pass commands through to dpkg-deb, rather than call dpkg-deb directly.

Actions

-b dir [archive], --build dir [archive]

Create an archive from the filesystem tree starting with directory dir. The directory must have a DEBIAN subdirectory containing the control file and any other control information. If archive is specified and is a filename, the package is written to that file; if no archive is specified, the package is written to dir.deb. If the archive already exists, it is replaced. If archive is the name of a directory, dpkg-deb looks in the control file for the information it needs to generate the package name. (Note that for this reason, you cannot use --nocheck with a directory name.)

-c archive, --contents archive

List the filesystem-tree portion of archive.

-e archive [dir], --control archive [dir]

Extract control information from archive into the directory dir, which is created if it doesn't exist. If dir is omitted, a DEBIAN subdirectory in the current directory is used.

-f archive [control-fields], --field archive [control-fields]

Extract information about one or more fields in the control file for archive. If no fields are provided, print the entire control file.

-h, --help

Print help information and exit.

-I archive [control-files], --info archive [control-files]

Write information about binary package archive to standard output. If no control files are provided, print a summary of the package contents; otherwise, print the control files in the order they were specified. An error message is printed to standard error for any missing components.

--fsys-tarfile archive

Extract the filesystem tree from archive, and send it to standard output in tar format. Can be used with tar to extract individual files from an archive.

--license, --licence

Print the license information and exit.

--version

Print the version number and exit.

-W archive, --show archive archive

Show information about the specified archive. The output can be customized with the --showformat option.

-x archive dir, --extract archive dir

-X archive dir, --vextract archive dir

Extract the filesystem tree from archive into the specified directory, creating dir if it doesn't already exist. -x (--extract) works silently, while -X (--vextract) lists the files as it extracts them. Do not use this action to install packages; use dpkg instead.

Options

-D, --debug

Turn on debugging.

--new

Build a new-style archive format (this is the default).

--nocheck

Don't check the control file before building an archive. This lets you build a broken archive.

--old

Build an old-style archive format.

--showformat=format

Specify the output format for -W/--show. The format can include the standard escape sequences \n (newline), \r (carriage return), or \\ (backslash). Specify package fields with the syntax ${var[;width]}. Fields are right-aligned by default, or left-aligned if width is negative.

-z#

Set the compression level to the value specified by #.

-Z type

Set the type of compression to use when building an archive. Possible values are: gzip, bzip2, and none.

dpkg-query
dpkg-query [option] command

Display information about packages listed in the dpkg database. You can also use dpkg-query as a backend for dpkg, instead of calling dpkg-query directly

Commands

--help

Print help information and exit.

-l [patterns], --list [patterns]

List packages whose names match any of the specified patterns. With no pattern specified, list all packages in /var/lib/dpkg/available. The pattern may need to be in quotes to avoid expansion by the shell.

-L packages, --listfiles packages

List files installed on your system from each of the specified packages. This command does not list files created by package-specific installation scripts.

--license, --licence

Print the license information and exit.

-p package, --print-avail package

Display details for the specified package, as found in /var/lib/dpkg/available.

-s package, --status package

Report on the status of the specified package.

-S patterns, --search patterns

Search the installed packages for filenames matching one of the specified patterns. At least one pattern must be specified.

-W [patterns], --show [patterns]

Like -l, but the output can be customized with the --showformat option.

--version

Print version information and exit.

Options

--admindir=dir

Use dir as the location of the dpkg database. The default is /var/lib/dpkg.

--showformat=format

Specify the output format for -W/--show. The format can include the standard escape sequences \n (newline), \r (carriage return), or \\ (backslash). Specify package fields with the syntax ${var[;width]}. Fields are right-aligned by default, or left-aligned if width is negative.

dpkg-split
dpkg-split [action] [options]

Split a binary package into smaller pieces and reassemble the pieces, either manually or in automatic mode. The automatic mode maintains a queue of parts for reassembling. Useful for transferring to and from floppy disks on older systems.

Actions

-a -o output part, --auto -o output part

Add part to the queue for automatic reassembly, and if all the parts are available, reassemble the package as output. Requires the use of the -o (or --output) option, as shown.

-d [packages], --discard [packages]

Discard parts from the automatic-assembly queue. If any packages are specified, discard only parts from those packages. Otherwise, empty the queue.

-I parts, --info parts

Print information about the specified part file or files to standard output.

-j parts, --join parts

Join the parts of a package file together from the parts specified. The default output file is package-version.deb.

-l, --listq

List the contents of the queue of parts waiting for reassembly, giving the package name, the parts that are on the queue, and the number of bytes.

-s full-package [prefix], --split full-package [prefix]

Split the package full-package into parts N of M, named prefixNofM.deb. The prefix defaults to the full-package name without the .deb extension.

-h, --help

Print help message and exit.

--license, --licence

Print license information and exit.

--version

Print version information and exit.

Options

--depotdir dir

Specify an alternate directory dir for the queue of parts waiting for reassembly. Default is /var/lib/dpkg.

--msdos

Force --split output filenames to be MS-DOS-compatible.

-Q, --npquiet

Do not print an error message for a part that doesn't belong to a binary package when doing automatic queuing or reassembly.

-O output, --output output

Use output as the filename for a reassembled package.

-S num, --partsize num

When splitting, specify the maximum part size (num) in kilobytes. Default is 450 KB.

dselect
dselect [options] [action]

A screen-oriented user frontend to dpkg. One of the primary user interfaces for installing and managing packages. See dpkg and dpkg-deb for information on building packages.

Actions

If dselect is run with no action specified on the command line, it displays the following menu:

     * 0. [A]ccess     Choose the access method to use.
       1. [U]pdate   Update list of available packages, if
                     possible.
       2. [S]elect   Request which packages you want on your
                     system.
       3. [I]nstall  Install and upgrade wanted packages.
       4. [C]onfig   Configure any packages that are
                     unconfigured.
       5. [R]emove   Remove unwanted software.
       6. [Q]uit     Quit dselect.

The asterisk (on the first line) shows the currently selected option. Any of the menu items can be specified directly on the command line as an action (access, update, select, install, config, remove, quit) to go directly to the desired activity. For example:

    $ dselect access

If you enter quit on the command line, dselect exits immediately without doing anything. An additional command-line action is menu, which displays the menu and is equivalent to running dselect with no action.

Options

Options can be specified both on the command line and in the dselect configuration file, /etc/dpkg/dselect.cfg.

--admindir dir

Change the directory that holds internal datafiles to dir. Default is /var/lib/dpkg.

--color colorspec, --colour colorspec

Set colors for different parts of the screen, as specified by colorspec as follows:

    screenpart:[fgcolor],[bgcolor][:attr[+attr+...]]

This option can be specified multiple times, to override the default colors for different screenparts. Rather than having to specify the colors on the command line each time you run dselect, you might prefer to set them in the configuration file. The possible screen parts (going from the top of the screen to the bottom) are:

title

The screen title.

listhead

The header line above the package list.

list

The scrolling list of packages and some help text.

listsel

The selected item in the list.

pkgstate

The text showing the current state of each package.

pkgstatesel

The text showing the current state of the selected package.

infohead

The header line showing the state of the selected package.

infodesc

The short description of the package.

info

The text that displays information such as the package description.

infofoot

The last line of the screen when selecting packages.

query

Query lines.

helpscreen

The color of help screens.

Either the foreground color, the background color, or both can be specified for each screen part. The colors are given as the standard curses colors. After the color specification, you can specify a list of attributes separated by plus signs (+). The possible attributes are normal, standout, underline, reverse, blink, bright, dim, and bold. Not all attributes work on all terminals.

--expert

Run in expert mode; don't print help messages.

-D [file], --debug [file]

Turn on debugging. Send output to file if specified.

--help

Print help message and exit.

--license, licence

Print license information and exit.

--version

Print version information and exit.

synaptic
synaptic [options]

Graphical frontend for APT. Use in place of apt-get to install, upgrade, or remove packages from your system. With synaptic, you can view a list of all available packages, or you can break the list down in various ways to make it more manageable. From the synaptic window, you can select from a list of categories. The categories are section (e.g., view only development-related packages), package status, alphabetic (e.g., view only packages whose name starts with the letter A), search history, or filter.

If you choose to display by filter, there are a set of predefined filters, or you can define your own. The predefined filters include ones to display all packages, packages marked for a status change, packages that can be configured with debconf (Debian systems only), packages with broken dependencies, and packages that can be upgraded to a later version. You can edit the existing filters or define your own, by selecting Preferences [image] Filters from the Edit menu.

Once you've used the selection criteria to find the list of packages, you can select a single package, or you can select multiple packages by holding down the Shift or Ctrl key. Like apt-get, first do an update to update the package lists, then you can do an install or upgrade.

To start synaptic from Gnome, select System tools [image] Synaptic Package Manager from the Application menu. From the KDE menu, select Settings [image] Extra [image] Synaptic Package Manager. You can also start the graphical interface from the command line, with the command:

    synaptic  [options ]

Options

In addition to the following options, synaptic accepts the standard GTK+ toolkit command-line options.

-f filename, --filter-file=filename

Use the specified file as an alternative filter settings file.

-h, --help

Print help message and exit.

-i num, --initial-filter=num

Start up with the filter numbered numas the initial filter.

--non-interactive

Run without prompting for user input.

-ooption,--option=option

Set an internal option. Don't use this option unless you are sure you know what you are doing.

-r

Open with the file repository window displayed. This window lists the repositories and shows which are active.


Chapter 6. The Bash Shell and Korn Shell

The original Bourne shell distributed with V7 Unix in 1979 became the standard shell for writing shell scripts. The Bourne shell is still to be found in /bin/sh on many commercial Unix systems. It hasn't changed that much since its initial release, although it has seen modest enhancements over the years. The most notable new features were the CDPATH variable and a built-in test command with System III (circa 1980), command hashing and shell functions for System V Release 2 (circa 1984), and the addition of job control features for System V Release 4 (1989).

Because the Berkeley C shell (csh) offered features that were more pleasant for interactive use, such as command history and job control, for a long time the standard practice in the Unix world was to use the Bourne shell for programming and the C shell for daily use. David Korn at Bell Labs was the first developer to enhance the Bourne shell by adding csh-like features to it: history, job control, and additional programmability. Eventually, the Korn shell's feature set surpassed both the Bourne shell and the C shell, while remaining compatible with the Bourne shell for shell programming. Today, the POSIX standard defines the "standard shell" language and behavior based on the System V Bourne shell, with a selected subset of features from the Korn shell.

The Free Software Foundation, in keeping with its goal to produce a complete Unix work-alike system, developed a clone of the Bourne shell, written from scratch, named "Bash," the Bourne-Again SHell. Over time, Bash has become a POSIX-compliant version of the shell, with many additional features. A large part of these additional features overlap the features of the Korn shell, but Bash is not an exact Korn shell clone.

This chapter covers Bash, which is the primary shell for GNU/Linux. It also covers the two main versions of the Korn shell, ksh88 and ksh93. The following topics are presented:

  • Overview of features

  • Invoking the shell

  • Syntax

  • Functions

  • Variables

  • Arithmetic expressions

  • Command history

  • Job control

  • Command execution

  • Restricted shells

  • Built-in commands

http://www.gnu.org/software/bash/bash.html provides information about the Bash shell, as does http://cnswww.cns.cwru.edu/~chet/bash/bashtop.html. http://www.kornshell.com provides considerable information about the Korn shell. See also Classic Shell Scripting, Learning the Korn Shell, and Learning the bash Shell (all from O'Reilly).

All references in this chapter to the Bash shell are for Bash Version 3. Many of the features listed for ksh93 are found only in the version available from AT&T Research.


Section 6.1. Overview of Features

6.1. Overview of Features

The Bash and Korn shells provide the following features:

  • Input/output redirection

  • Wildcard characters (metacharacters) for filename abbreviation

  • Shell variables and options for customizing your environment

  • A built-in command set for writing shell programs

  • Shell functions, for modularizing tasks within a shell program

  • Job control

  • Command-line editing (using the command syntax of either vi or emacs)

  • Access to previous commands (command history)

  • Integer arithmetic

  • Arrays and arithmetic expressions

  • Command-name abbreviation (aliasing)

ksh93 and Bash (but not ksh88) have the following capabilities:

  • Upward compliance with POSIX

  • Internationalization facilities

  • An arithmetic for loop

  • More ways to substitute variables

ksh93 adds the following capabilities:

  • Floating-point arithmetic and built-in arithmetic functions

  • Structured variable names and indirect variable references

  • Associative arrays

  • More ways to match patterns


Section 6.2. Invoking the Shell

6.2. Invoking the Shell

The command interpreter for the Bash shell (bash) or the Korn shell (ksh) can be invoked as follows:

    bash  [options]  [arguments]

    ksh   [options]  [arguments]

ksh and Bash can execute commands from a terminal, from a file (when the first argument is an executable script), or from standard input (if no arguments remain or if -s is specified). Both shells automatically print prompts if standard input is a terminal, or if -i is given on the command line.

On Linux systems, /bin/sh is generally a link to Bash. When invoked as sh, Bash acts more like the traditional Bourne shell: Login shells read /etc/profile and ~/.profile, and regular shells read $ENV, if it's set. Full details are available on the bash(1) manpage.

6.2.1. Options

6.2.1.1 Common options

-c str

Read commands from string str.

-D

Print all $"..." strings in the program. Not ksh88.

-i

Create an interactive shell (prompt for input).

-p

Start up as a privileged user. Bash: Don't read $ENV or $BASH_ENV, don't import functions from the environment, and ignore the value of $SHELLOPTS. Korn shell: Don't process $HOME/.profile, read /etc/suid_profile instead of $ENV.

-r

Create a restricted shell.

-s

Read commands from standard input; output from built-in commands goes to file descriptor 1; all other shell output goes to file descriptor 2.

-, --

End option processing.

6.2.1.2 Bash options

-O option

Enable shopt option option.

--debugger

Read the debugging profile at startup, turn on the extdebug option to shopt, and enable function tracing. For use by the Bash debugger.

--dump-po-strings

Same as -D, but output in GNU gettext format.

--dump-strings

Same as -D.

--help

Print a usage message and exit successfully.

--init-file file

--rcfile file

Use file as the startup file instead of ~/.bashrc for interactive shells.

--login

Shell is a login shell.

--noediting

Do not use the readline library for input, even in an interactive shell.

--noprofile

Do not read /etc/profile or any of the personal startup files.

--norc

Do not read ~/.bashrc. Enabled automatically when invoked as sh.

--posix

Turn on POSIX mode.

--restricted

Same as -r.

--verbose

Same as set -v; the shell prints lines as it reads them.

--version

Print a version message and exit.

The remaining options to Bash and ksh are listed under the set built-in command.

6.2.2. Arguments

Arguments are assigned in order to the positional parameters $1, $2, etc. If the first argument is an executable script, commands are read from it, and the remaining arguments are assigned to $1, $2, etc. The name of the script is available as $0.


Section 6.3. Syntax

6.3. Syntax

This section describes the many symbols peculiar to the Bash and Korn shells. The topics are arranged as follows:

  • Special files

  • Filename metacharacters

  • Quoting

  • Command forms

  • Redirection forms

  • Coprocesses (Korn shell only)

6.3.1. Special Files

Both shells read one or more startup files. Some of the files are read only when a shell is a login shell.

The Korn shell reads these files:

  1. /etc/profile. Executed automatically at login, first.

  2. ~/.profile. Executed automatically at login, second.

  3. $ENV. Specifies the name of a file to read when a new Korn shell is created. (ksh88: all shells, ksh93: interactive shells only.) The value is a variable (ksh93: and command and arithmetic) substituted in order to determine the actual filename. Login shells read $ENV after processing /etc/profile and $HOME/.profile.

Bash reads these files:

  1. /etc/profile. Executed automatically at login, first.

  2. The first file found from this list: ~/.bash_profile, ~/.bash_login, or ~/.profile. Executed automatically at login, second.

  3. ~/.bashrc is read by every shell, after the login files. However, if invoked as sh, Bash instead reads $ENV, just as the Korn shell does.

For both shells, the getpwnam( ) and getpwuid( ) functions are are the sources of home directories for ~name abbreviations. (On single-user systems, the user database is stored in /etc/passwd. However on networked systems, this information may come from NIS, NIS+, or LDAPnot your workstation password file.)

6.3.2. Filename Metacharacters

Characters | Meaning
* | Match any string of zero or more characters.
? | Match any single character.
[abc...] | Match any one of the enclosed characters; a hyphen can specify a range (e.g., a-z, A-Z, 0-9).
[!abc...] | Match any character not enclosed as above.
~ | Home directory of the current user.
~name | Home directory of user name.
~+ | Current working directory ($PWD).
~- | Previous working directory ($OLDPWD).

In the Korn shell, or Bash with the extglob option on:

Characters | Meaning
?(pattern) | Match zero or one instance of pattern.
*(pattern) | Match zero or more instances of pattern.
+(pattern) | Match one or more instances of pattern.
@(pattern) | Match exactly one instance of pattern.
!(pattern) | Match any strings that don't match pattern.
\n | Match the text matched by the nth subpattern in (...). ksh93 only.

This pattern can be a sequence of patterns separated by |, meaning that the match applies to any of the patterns. This extended syntax resembles that available in egrep and awk. In the Korn shell, but not in Bash, if & is used instead of |, all the patterns must match. & has higher precedence than |.

ksh93 and Bash support the POSIX [[=c=]] notation for matching characters that have the same weight, and [[.c.]] for specifying collating sequences. In addition, character classes, of the form [[:class:]], allow you to match the following classes of characters.

Class | Class | Class | Class
alnum | Alphanumeric characters | graph | Nonspace characters
alpha | Alphabetic characters | print | Printable characters
blank | Space or tab | punct | Punctuation characters
cntrl | Control characters | space | Whitespace characters
digit | Decimal digits | upper | Uppercase characters
lower | Lowercase characters | xdigit | Hexadecimal digits

Bash and ksh93 also accept the [:word:] character class, which is not in POSIX. [[:word:]] is equivalent to [[:alnum:]_].

6.3.2.1 Examples
    $ ls new*       List new and new.1
    $ cat ch?       Match ch9 but not ch10
    $ vi [D-R]*     Match files that begin with uppercase D through R
    $ pr !(*.o|core) | lp       Print files that are not object files or core dumps

NOTE

On modern systems, ranges such as [D-R] are not portable; the system's locale may include more than just the uppercase letters from D to R in the range.

6.3.3. Quoting

Quoting disables a character's special meaning and allows it to be used literally, as itself. The following table displays characters that have special meaning to the Bash and Korn shells.

Character | Meaning
; | Command separator
& | Background execution
( ) | Command grouping
| | Pipe
< > & | Redirection symbols
* ? [ ] ~ + - @ ! | Filename metacharacters
" ' \ | Used in quoting other characters
' | Command substitution
$ | Variable substitution (or command or arithmetic substitution)
space tab newline | Word separators

These characters can be used for quoting:

" "

Everything between " and " is taken literally, except for the following characters that keep their special meaning:

$

Variable (or command and arithmetic) substitution will occur.

'

Command substitution will occur.

"

This marks the end of the double quote.

' '

Everything between ' and ' is taken literally except for another '. You cannot embed another ' within such a quoted string.

\

The character following a \ is taken literally. Use within " " to escape ", $, and '. Often used to escape itself, spaces, or newlines.

$" "

Not ksh88. Just like " ", except that locale translation is done.

$' '

Not ksh88. Similar to ' ', but the quoted text is processed for the following escape sequences:

Sequence | Value | Sequence | Value
\a | Alert | \t | Tab
\b | Backspace | \v | Vertical tab
\cX | Control character X | \nnn | Octal value nnn
\e | Escape | \xnn | Hexadecimal value nn
\E | Escape | \' | Single quote
\f | Form feed | \" | Double quote
\n | Newline | \\ | Backslash
\r | Carriage return |  |

6.3.3.1 Examples
    $ echo 'Single quotes "protect" double quotes'
    Single quotes "protect" double quotes
    $ echo "Well, isn't that \"special\"?"
    Well, isn't that "special"?
    $ echo "You have `ls | wc -l` files in `pwd`"
    You have      43 files in /home/bob
    $ echo "The value of \$x is $x"
    The value of $x is 100

6.3.4. Command Forms

Syntax | Effect
cmd & | Execute cmd in background.
cmd1 ; cmd2 | Command sequence; execute multiple cmds on the same line.
{ cmd1 ; cmd2 ; } | Execute commands as a group in the current shell.
(cmd1 ; cmd2) | Execute commands as a group in a subshell.
cmd1 | cmd2 | Pipe; use output from cmd1 as input to cmd2.
cmd1 'cmd2' | Command substitution; use cmd2 output as arguments to cmd1.
cmd1 $(cmd2) | POSIX shell command substitution; nesting is allowed.
cmd $((expression)) | POSIX shell arithmetic substitution. Use the result of expression as argument to cmd.
cmd1 && cmd2 | AND; execute cmd1 and then (if cmd1 succeeds) cmd2. This is a "short-circuit" operation; cmd2 is never executed if cmd1 fails.
cmd1 || cmd2 | OR; execute either cmd1 or (if cmd1 fails) cmd2. This is a "short-circuit" operation; cmd2 is never executed if cmd1 succeeds.
! cmd | NOT; execute cmd, and produce a zero exit status if cmd exits with a nonzero status. Otherwise, produce a nonzero status when cmd exits with a zero status. Not ksh88.

6.3.4.1 Examples
    $ nroff file > file.txt &  Format in the background
    $ cd; ls                          Execute sequentially
    $ (date; who; pwd) > logfile   All output is redirected
    $ sort file | pr -3 | lp          Sort file, page output, then print
    $ vi `grep -l ifdef *.c`          Edit files found by grep
    $ egrep '(yes|no)' `cat list`     Specify a list of files to search
    $ egrep '(yes|no)' $(cat list)    POSIX version of previous
    $ egrep '(yes|no)' $(< list)   Faster, not in POSIX
    $ grep XX file && lp file  Print file if it contains the pattern;
    $ grep XX file || echo "XX not found"  Otherwise, echo an error message

6.3.5. Redirection Forms

File descriptor | Name | Common abbreviation | Typical default
0 | Standard input | stdin | Keyboard
1 | Standard output | stdout | Screen
2 | Standard error | stderr | Screen

The usual input source or output destination can be changed, as seen in the following sections.

6.3.5.1 Simple redirection

cmd > file

Send output of cmd to file (overwrite).

cmd >> file

Send output of cmd to file (append).

cmd < file

Take input for cmd from file.

cmd << text

The contents of the shell script up to a line identical to text become the standard input for cmd (text can be stored in a shell variable). This command form is sometimes called a Here document. Input is usually typed at the keyboard or in the shell program. Commands that typically use this syntax include cat, ex, and sed. (If <<- is used, leading tabs are stripped from the contents of the here document, and the tabs are ignored when comparing input with the end-of-input text marker.) If any part of text is quoted, the input is passed through verbatim. Otherwise, the contents are processed for variable, command, and arithmetic substitutions.

cmd <<< word

Supply text of word, with trailing newline, as input to cmd. (This is known as a here string, from the free version of the rc shell.) Not ksh88.

cmd <> file

Open file for reading and writing on the standard input. The contents are not destroyed.[*]

[*] With <, the file is opened read-only, and writes on the file descriptor will fail. With <>, the file is opened read-write; it is up to the application to actually take advantage of this.

cmd >| file

Send output of cmd to file (overwrite), even if the shell's noclobber option is set.

6.3.5.2 Redirection using file descriptors

Syntax | Effect
cmd >&n | Send cmd output to file descriptor n.
cmd m>&n | Same, except that output that would normally go to file descriptor m is sent to file descriptor n instead.
cmd >&- | Close standard output.
cmd <&n | Take input for cmd from file descriptor n.
cmd m<&n | Same, except that input that would normally come from file descriptor m comes from file descriptor n instead.
cmd <&- | Close standard input.
cmd <&n- | Move input file descriptor n instead of duplicating it. Not ksh88.
cmd >&n- | Move output file descriptor n instead of duplicating it. Not ksh88.

6.3.5.3 Multiple redirection

Syntax | Effect
cmd 2>file | Send standard error to file ; standard output remains the same (e.g., the screen).
cmd > file 2>&1 | Send both standard error and standard output to file.
cmd &> file | Same. Bash only, preferred form.
cmd >& file | Same. Bash only.
cmd > f1 2>f2 | Send standard output to file f1, standard error to file f2.
cmd | tee files | Send output of cmd to standard output (usually the terminal) and to files. (See the Example in Chapter 3 under tee.)
cmd 2>&1 | tee files | Send standard output and error output of cmd to standard output (usually the terminal) and to files.

No space should appear between file descriptors and a redirection symbol; spacing is optional in the other cases.

Bash allows multi-digit file descriptor numbers. The other shells do not.

6.3.5.4 Examples
    $ cat part1 > book
    $ cat part2 part3 >> book
    $ mail tim < report
    $ sed 's/^/XX /g' << END_ARCHIVE
    > This is often how a shell archive is "wrapped",
    > bundling text for distribution.  You would normally
    > run sed from a shell program, not from the command line.
    > END_ARCHIVE
    XX This is often how a shell archive is "wrapped",
    XX bundling text for distribution.  You would normally
    XX run sed from a shell program, not from the command line.

To redirect standard output to standard error:

    $ echo "Usage error:  see administrator" 1>&2

The following command sends output (files found) to filelist and error messages (inaccessible files) to file no_access:

    $ find / -print > filelist 2>no_access

6.3.6. Coprocesses

Coprocesses are a feature of the Korn shell only.

Syntax | Syntax
cmd1 | cmd2 |& | Coprocess; execute the pipeline in the background. The shell sets up a two-way pipe, allowing redirection of both standard input and standard output.
read -p var | Read coprocess output into variable var.
print -p string | Write string to the coprocess.
cmd <&p | Take input for cmd from the coprocess.
cmd >&p | Send output of cmd to the coprocess.
exec n<&p | Move input from coprocess to file descriptor n.
exec n>&p | Move output for coprocess to file descriptor n.

Moving the coprocess input and output file descriptors to standard file descriptors allows you to open multiple coprocesses.

6.3.6.1 Examples
    $ ed - memo |&         Start coprocess
    $ print -p /word/          Send ed command to coprocess
    $ read -p search           Read output of ed command into variable search
    $ print "$search"          Show the line on standard output
    A word to the wise.


Section 6.4. Functions

6.4. Functions

A shell function is a grouping of commands within a shell script. Shell functions let you modularize your program by dividing it up into separate tasks. This way the code for each task need not be repeated every time you need to perform the task. The POSIX shell syntax for defining a function follows the Bourne shell:

    name (  ) {
        function body's code come here
    }

Functions are invoked just as are regular shell built-in commands or external commands. The command line parameters $1, $2 and so on receive the function's arguments, temporarily hiding the global values of $1, etc. For example:

    # fatal --- print an error message and die:

    fatal (  ) {
        echo "$0: fatal error:" "$@" >&2     # messages to standard error
        exit 1
    }
    ...
    if [ $# = 0 ]    # not enough arguments
    then
        fatal not enough arguments
    fi

A function may use the return command to return an exit value to the calling shell program. Be careful not to use exit from within a function unless you really wish to terminate the entire program.

Bash and the Korn shell allow you to define functions using an additional keyword, function, as follows:

    function fatal {
        echo "$0: fatal error:" "$@" >&2     # messages to standard error
        exit 1
    }

When working with the different shells and defining functions, there are semantic differences that should be kept in mind:

  • In Bash, all functions share traps with the "parent" shell (except the DEBUG trap, if function tracing has been turned on). With the errtrace option enabled (either set -E or set -o errtrace), functions also inherit the ERR trap. If function tracing has been enabled, functions inherit the RETURN trap. Functions may have local variables, and they may be recursive. The syntax used to define a function is irrelevant.

  • In ksh88, all functions have their own traps and local variables, and may be recursive.

  • In ksh93, name ( ) functions share traps with the "parent" shell and may not be recursive.

  • In ksh93, function functions have their own traps and local variables, and may be recursive. Using the . command with a function function gives it POSIX shell semantics (i.e., shared traps and variables).


Section 6.5. Variables

6.5. Variables

This section describes the following:

  • Variable substitution

  • Built-in shell variables

  • Other shell variables

  • Arrays

  • Discipline functions (ksh93 only)

  • Special prompt strings

6.5.1. Variable Substitution

ksh93 provides structured variables, such as pos.x and pos.y. To create either one, pos must already exist, and braces must be used to retrieve their values. Names beginning with .sh are reserved for use by ksh.

No spaces should be used in the following expressions. The colon (:) is optional; if it's included, var must be nonnull, as well as set.

Variable expression | Description
var=value ... | Set each variable var to a value.
${var} | Use value of var; braces are optional if var is separated from the following text. They are required for array variables, and in ksh93 if a variable name contains periods.
${var:-value} | Use var if set; otherwise, use value.
${var:=value} | Use var if set; otherwise, use value and assign value to var.
${var:?value} | Use var if set; otherwise, print value and exit (if not interactive). If value isn't supplied, print the phrase "parameter null or not set."
${var:+value} | Use value if var is set; otherwise, use nothing.
${#var} | Use the length of var.
${#*} | Use the number of positional parameters.
${#@} |
${var#pattern} | Use value of var after removing pattern from the left. Remove the shortest matching piece.
${var##pattern} | Same as #pattern, but remove the longest matching piece.
${var%pattern} | Use value of var after removing pattern from the right. Remove the shortest matching piece.
${var%%pattern} | Same as %pattern, but remove the longest matching piece.

In ksh93 and Bash:

Variable expression | Description
${!prefix*} | List of variables whose names begin with prefix.
${!prefix@} |
${var:pos} | Starting at position pos (0-based) in variable var, extract len characters, or rest of string if no len. pos and len may be arithmetic expressions.
${var:pos:len} |
${var/pat/repl} | Use value of var, with first match of pat replaced with repl.
${var/pat} | Use value of var, with first match of pat deleted.
${var//pat/repl} | Use value of var, with every match of pat replaced with repl.
${var/#pat/repl} | Use value of var, with match of pat replaced with repl. Match must occur at beginning of the value.
${var/%pat/repl} | Use value of var, with match of pat replaced with repl. Match must occur at end of the value.

In ksh93, indirect variables allow you to "alias" one variable name to affect the value of another. This is accomplished using typeset -n:

    $ greet="hello, world"              Create initial variable
    $ typeset -n friendly_message=greet        Set up alias
    $ echo $friendly_message            Access old value through new name
    hello, world
    $ friendly_message="don't panic"           Change the value
    $ echo $greet                Old variable is changed
    don't panic

Bash has a similar mechanism for indirect variable referencing:

    $ greet="hello, world"              Create initial variable
    $ friendly_message=greet            Aliasing variable
    $ echo ${!friendly_message}         Use the alias
    hello, world

6.5.1.1 Examples
    $ u=up d=down blank=        Assign values to three variables (last is null)
    $ echo ${u}root             Braces are needed here
    uproot
    $ echo ${u-$d}              Display value of u or d; since u is set, it's printed
    up
    $ echo ${tmp-`date`}        If tmp is not set, the date command is executed
    Mon Aug 30 11:15:23 EDT 2004
    $ echo ${blank="no data"}          blank is set, so it is printed (a blank line)
    $ echo ${blank:="no data"}         blank is set but null, so the string is printed
    no data
    $ echo $blank               blank now has a new value
    no data
    $ tail=${PWD##*/}          Take the current directory name and remove the
                                longest character string ending with /, which removes
                                the leading pathname and leaves the tail

6.5.2. Built-in Shell Variables

Built-in variables are automatically set by the shell and are typically used inside shell scripts. Built-in variables can make use of the variable substitution patterns shown previously. Note that the $S is not actually part of the variable name, although the variable is always referenced this way. The following are available in any Bourne-compatible shell.

Variable | Variable
$# | Number of command-line arguments.
$- | Options currently in effect (arguments supplied on command line or to set).
$? | Exit value of last executed command.
$$ | Process number of current process.
$! | Process number of last background command.
$0 | First word; that is, command name. This will have the full pathname if it was found via a PATH search.
$n | Individual arguments on command line (positional parameters). The Bourne shell allows only nine parameters to be referenced directly (n = 1-9); Bash and the Korn shell allow n to be greater than 9 if specified as ${n}.
$*, $@ | All arguments on command line ($1 $2 ...).
"$*" | All arguments on command line as one string ("$1 $2..."). The values are separated by the first character in IFS.
"$@" | All arguments on command line, individually quoted ("$1" "$2" ...).

Bash and the Korn shell automatically set these additional variables.

Variable | Variable
$_ | Temporary variable; initialized to pathname of script or program being executed. Later, stores the last argument of previous command. Also stores name of matching MAIL file during mail checks.
HISTCMD | The history number of the current command.
LINENO | Current line number within the script or function.
OLDPWD | Previous working directory (set by cd).
OPTARG | Name of last option processed by getopts.
OPTIND | Numerical index of OPTARG.
PPID | Process number of this shell's parent.
PWD | Current working directory (set by cd).
RANDOM[=n] | Generate a new random number with each reference; start with integer n, if given.
REPLY | Default reply, used by select and read.
SECONDS[=n] | Number of seconds since the shell was started, or, if n is given, number of seconds + n since the shell started.

ksh93 automatically sets these additional variables. Variables whose names contain "." must be enclosed in braces when referencede.g., ${.sh.edchar}.

Variable | Variable
.sh.edchar | The character(s) entered when processing a KEYBD trap. Changing it replaces the characters that caused the trap.
.sh.edcol | The position of the cursor in the most recent KEYBD trap.
.sh.edmode | Will be equal to Escape if in a KEYBD trap in vi mode; otherwise empty.
.sh.edtext | The characters in the input buffer during a KEYBD trap.
.sh.match | Array variable containing text matched during a variable substitution. Index 0 is the entire value; the others correspond to parenthesized subexpressions.
.sh.name | The name of the variable running a discipline function.
.sh.subscript | The subscript of the variable running a discipline function.
.sh.value | The value of the variable inside the set and get discipline functions.
.sh.version | The version of ksh93.

Bash automatically sets these additional variables. Many of these variables are for use by the Bash Debugger (see http://bashdb.sourceforge.net) or for providing programmable completion (see the section Programmable Completion (Bash only)," later in this chapter).

Variable | Variable
BASH | The full pathname used to invoke this instance of Bash.
BASH_ARGC | Array variable. Each element holds the number of arguments for the corresponding function or dot-script invocation. Set only in extended debug mode, with shopt -s extdebug.
BASH_ARGV | An array variable similar to BASH_ARGC. Each element is one of the arguments passed to a function or dot-script. It functions as a stack, with values being pushed on at each call. Thus, the last element is the last argument to the most recent function or script invocation. Set only in extended debug mode, with shopt -s extdebug.
BASH_COMMAND | The command currently executing or about to be executed. Inside a trap handler, it is the command running when the trap was invoked.
BASH_EXECUTION_STRING | The string argument passed to the -c option.
BASH_LINENO | Array variable, corresponding to BASH_SOURCE and FUNCNAME. For any given function number i (starting at 0), ${FUNCNAME[i]} was invoked in file ${BASH_SOURCE[i]} on line ${BASH_LINENO[i]}. The information is stored with the most recent function invocation first.
BASH_REMATCH | Array variable, assigned by the =~ operator of the [[ ]] construct. Index 0 is the text that matched the entire pattern. The other indices are the text matched by parenthesized subexpressions. This variable is read-only.
BASH_SOURCE | Array variable, containing source filenames. Each element corresponds with those in FUNCNAME and BASH_LINENO.
BASH_SUBSHELL | This variable is incremented by one each time a subshell or subshell environment is created.
BASH_VERSINFO[0] | The major version number, or release, of Bash.
BASH_VERSINFO[1] | The minor version number, or version, of Bash.
BASH_VERSINFO[2] | The patch level.
BASH_VERSINFO[3] | The build version.
BASH_VERSINFO[4] | The release status.
BASH_VERSINFO[5] | The machine type; same value as in MACHTYPE.
BASH_VERSION | A string describing the version of Bash.
COMP_CWORD | For programmable completion. Index into COMP_WORDS, indicating the current cursor position.
COMP_LINE | For programmable completion. The current command line.
COMP_POINT | For programmable completion. The position of the cursor as a character index in COMP_LINE.
COMP_WORDBREAKS | For programmable completion. The characters that the readline library treats as word separators when doing word completion.
COMP_WORDS | For programmable completion. Array variable containing the individual words on the command line.
DIRSTACK | Array variable, containing the contents of the directory stack as displayed by dirs. Changing existing elements modifies the stack, but only pushd and popd can add or remove elements from the stack.
EUID | Read-only variable with the numeric effective UID of the current user.
FUNCNAME | Array variable, containing function names. Each element corresponds with those in BASH_SOURCE and BASH_LINENO.
GROUPS | Array variable containing the list of numeric group IDs in which the current user is a member.
HISTCMD | The history number of the current command.
HOSTNAME | The name of the current host.
HOSTTYPE | A string that describes the host system.
MACHTYPE | A string that describes the host system in the GNU cpu-company-system format.
OSTYPE | A string that describes the operating system.
PIPESTATUS | An array variable containing the exit statuses of the commands in the most recent foreground pipeline.
SHELLOPTS | A colon-separated list of shell options (for set -o). If set in the environment at startup, Bash enables each option present in the list.
SHLVL | Incremented by one every time a new Bash starts up.
UID | Read-only variable with the numeric real UID of the current user.

6.5.3. Other Shell Variables

The following variables are not automatically set by the shell, although many of them can influence the shell's behavior. They are typically used in your .profile file, where you can define them to suit your needs. Variables can be assigned values by issuing commands of the form:

    variable=value

This list includes the type of value expected when defining these variables. Those that are specific to the Bash shell are marked as (B). Those that are specific to the Korn shell are marked as (K). Those that are specific to ksh93 are marked (K93).

Variable expression

Variable expression

CDPATH=dirs

Directories searched by cd; allows shortcuts in changing directories; unset by default.

COLUMNS=n

Screen's column width; used in line edit modes and select lists.

COMPREPLY=(words ...)

(B) Array variable from which Bash reads the possible completions generated by a completion function.

EDITOR=file

(K) Pathname of line-edit mode to turn on (can end in emacs or vi); used when VISUAL is not set.

EMACS

(B) If the value starts with t, Bash assumes it's running in an Emacs buffer and disables line editing.

ENV=file

Name of script that gets executed at startup; useful for storing alias and function definitions. For example, ENV=$HOME/.kshrc.

FCEDIT=file

Editor used by fc command (default is /bin/ed). Obsoleted in ksh93 by HISTEDIT.

FIGNORE=pattern

(K93) Pattern describing the set of filenames to ignore during pattern matching. (B) Similar: colon-separated list of patterns describing filenames to ignore when doing filename completion.

FPATH=dirs

(K) Directories to search for function definitions; undefined functions are set via typeset -fu; FPATH is searched when these functions are first referenced. (ksh93 also searches PATH.)

GLOBIGNORE=patlist

(B) Colon-separated list of patterns describing the set of filenames to ignore during pattern matching.

HISTCONTROL=list

(B) Colon-separated list of values controlling how commands are saved in the history file. Recognized values are: ignoredups, ignorespace, ignoreboth, and erasedups.

HISTEDIT=file

(K93) Editor used by hist command, if set. Overrides the setting of FCEDIT.

HISTFILE=file

File in which to store command history. For ksh, it must be set before ksh is started, and the default is $HOME/.sh_history. If you use both Bash and ksh, be sure to have different files for this value, as the format of the saved history file is not compatible between the two shells.

HISTFILESIZE=n

(B) Number of lines to be kept in the history file. This may be different than the number of commands.

HISTIGNORE=list

(B) A colon-separated list of patterns that must match the entire command line. Matching lines are not saved in the history file. An unescaped & in a pattern matches the previous history line.

HISTSIZE=n

Number of history commands to be kept in the history file.

HISTTIMEFORMAT=string

(B) A format string for strftime(3) to use for printing timestamps along with commands from the history command. If set (even if null), Bash saves timestamps in the history file along with the commands.

HOME=dir

Home directory; set by login (from /etc/passwd file).

HOSTFILE=file

(B) Name of a file in the same format as /etc/hosts that Bash should use to find hostnames for hostname completion.

IFS='chars'

Input field separators; default is space, tab, and newline.

IGNOREEOF=n

(B) Numeric value indicating how many successive EOF characters must be typed before Bash exits. If null or nonnumeric value, default is 10.

INPUTRC=file

(B) Initialization file for the readline library. This overrides the default value of ~/.inputrc.

LANG=dir

Default value for locale, used if no LC_* variables are set.

LC_ALL=locale

(B, K93) Current locale; overrides LANG and the other LC_* variables.

LC_COLLATE=locale

(B, K93) Locale to use for character collation (sorting order).

LC_CTYPE=locale

(B, K93) Locale to use for character class functions. (See the earlier section Filename Metacharacters.")

LC_MESSAGES=locale

(B) Locale to use for translating $"..." strings.

LC_NUMERIC=locale

(B, K93) Locale to use for the decimal-point character.

LINES=n

Screen's height; used for select lists.

MAIL=file

Default file to check for incoming mail; set by login.

MAILCHECK=n

Number of seconds between mail checks; default is 600 (10 minutes).

MAILPATH=files

One or more files, delimited by a colon, to check for incoming mail. Along with each file, you may supply an optional message that the shell prints when the file increases in size. Messages are separated from the filename by a ? character, and the default message is You have mail in $_. $_ is replaced with the name of the file. For example, you might have:

    MAILPATH="$MAIL?Ring! Candygram!:/etc/motd?New Login Message"

OPTERR=n

(B) When set to 1 (the default value), Bash prints error messages from the built-in getopts command.

PATH=dirlist

One or more pathnames, delimited by colons, in which to search for commands to execute. Default for many systems is /bin:/usr/bin. On Solaris, the default is /usr/bin:. However, the standard start-up scripts change it to:

    /usr/bin:/usr/ucb:/etc:.

ksh93: PATH is also searched for function definitions for undefined functions.

POSIXLY_CORRECT=string

(B) When set at startup or while running, Bash enters POSIX mode, disabling behavior and modifying features that conflict with the POSIX standard.

PROMPT_COMMAND=command

(B) If set, Bash executes this command each time before printing the primary prompt.

PS1=string

Primary prompt string; default is $.

PS2=string

Secondary prompt (used in multiline commands); default is >.

PS3=string

Prompt string in select loops; default is #?.

PS4=string

Prompt string for execution trace (ksh -x, bash -x, or set -x); default is +.

SHELL=file

Name of default shell (e.g., /bin/sh). Bash sets this if it's not in the environment at startup.

TERM=string

Terminal type.

TIMEFORMAT=string

(B) A format string for the output for the time keyword.

TMOUT=n

If no command is typed after n seconds, exit the shell. Also affects the read command and the select loop.

VISUAL=path

(K) Same as EDITOR, but VISUAL is checked first.

auto_resume=list

(B) Enables the use of simple strings for resuming stopped jobs. With a value of exact, the string must match a command name exactly. With a value of substring, it can match a substring of the command name.

histchars=chars

(B) Two or three characters that control Bash's csh-style history expansion. The first character signals a history event. The second is the "quick substitution" character, and the third indicates the start of a comment. The default value is !^#.

6.5.4. Arrays

Both shells support one-dimensional arrays. The first element is numbered 0. Bash has no limit on the number of elements. ksh88 allowed up 1024 elements, early versions of ksh93 allowed at least 4096 elements, and modern versions allow up to 65,536 elements. Arrays are initialized with a special form of assignment:

    message=(hi there how are you today)          Bash and ksh93

where the specified values become elements of the array. The Korn shell has an additional syntax:

    set -A message hi there how are you today     Ksh88 and ksh93

Individual elements may also be assigned to:

    message[0]=hi            This is the hard way
    message[1]=there
    message[2]=how
    message[3]=are
    message[4]=you
    message[5]=today

Declaring arrays is not required. Any valid reference to a subscripted variable can create an array.

When referencing arrays, use the ${ ... } syntax. This isn't needed when referencing arrays inside (( )) (the form of let that does automatic quoting). Note that [ and ] are typed literally (i.e., they don't stand for optional syntax).

Syntax | Effect
${name[i]} | Use element i of array name. i can be any arithmetic expression as described under let.
${name} | Use element 0 of array name.
${name[*]} | Use all elements of array name.
${name[@]} |
${#name[*]} | Use the number of elements in array name.
${#name[@]} |

ksh93 provides associative arrays, where the indices are strings instead of numbers (as in awk). In this case, [ and ] act like double quotes. Associative arrays are created with typeset -A. A special syntax allows assigning to multiple elements at once:

    data=([joe]=30 [mary]=25)

The values would be retrieved as ${data[joe]} and ${data[mary]}.

6.5.5. Discipline Functions (ksh93 only)

Along with structured variables, ksh93 introduces discipline functions. These are special functions that are called whenever a variable's value is accessed or changed. For a shell variable named x, you can define the following functions:

x.get

Called when x's value is retrieved ($x).

x.set

Called when x's value is changed (x=2).

x.unset

Called when x is unset (unset x).

Within the discipline functions, special variables provide information about the variable being changed:

.sh.name

The name of the variable being changed.

.sh.subscript

The subscript of the array element being changed.

.sh.value

The value of the variable being assigned or returned. Changing it within the discipline function changes the value that is actually assigned or returned.

6.5.6. Special Prompt Strings

Both shells process the value of PS1 for special strings. The Korn shell expands a single ! into the current command number. Use !! to get a literal !. For example:

    PS1='cmd !> '

Bash processes the values of PS1, PS2, and PS4 for the following special escape sequences.

Escape sequence | Description
\a | An ASCII BEL character (octal 07).
\A | The current time in 24-hour HH:MM format.
\d | The date in "weekday month day" format.
\D{format} | The date as specified by the strftime(3) format format. The braces are required.
\e | An ASCII Escape character (octal 033).
\h | The hostname, up to the first period.
\H | The full hostname.
\j | The current number of jobs.
\l | The basename of the shell's terminal device.
\n | A newline character.
\r | A carriage-return character.
\s | The name of the shell (basename of $0).
\t | The current time in 24-hour HH:MM:SS format.
\T | The current time in 12-hour HH:MM:SS format.
\u | The current user's username.
\v | The version of Bash.
\V | The release (version plus patch level) of Bash.
\w | The current directory, with $HOME abbreviated as ~.
\W | The basename of the current directory, with $HOME abbreviated as ~.
\! | The history number of this command.
\# | The command number of this command.
\$ | If the effective UID is 0, a #; otherwise a $.
\@ | The current time in 12-hour a.m./p.m. format.
\nnn | The character represented by octal value nnn.
\\ | A literal backslash.
\[ | Start a sequence of nonprinting characters, such as for highlighting or changing colors on a terminal.
\] | End a sequence of nonprinting characters.

In addition, some or all of the PS1-PS4 variables undergo different substitutions, as outlined in the following table.

Substitution | ksh88 | ksh93 | Bash
! for command number | PS1 | PS1 |
Escape sequences |  |  | PS1, PS2, PS4
Variable substitution | PS1 | PS1 | PS1, PS2, PS4
Command substitution |  | PS1 | PS1, PS2, PS4
Arithmetic substitution |  | PS1 | PS1, PS2, PS4

In Bash, the escape sequences are processed first, and then, if the promptvars shell option is enabled via the shopt command (the default), the substitutions are performed.


Section 6.6. Arithmetic Expressions

6.6. Arithmetic Expressions

The let command performs arithmetic. ksh88 and Bash are restricted to integer arithmetic. ksh93 can do floating-point arithmetic as well. Both shells provide a way to substitute arithmetic values (for use as command arguments or in variables); base conversion is also possible.

Expression | Meaning
$(( expr )) | Use the value of the enclosed arithmetic expression.
B#n | Interpret integer n in numeric base B. For example, 8#100 specifies the octal equivalent of decimal 64.

6.6.1. Operators

The shells use arithmetic operators from the C programming language; the following table listing is in decreasing order of precedence. ksh88 does not support the ++, --, unary +, ?:, comma or ** operators. Early versions of ksh93 do not have **.

Operator | Operator
++ -- | Auto-increment and auto-decrement, both prefix and postfix.
+ - ! ~ | Unary plus and minus, logical negation and binary inversion (one's complement).
** | Exponentiation.[a]
* / % | Multiplication; division; modulus (remainder).
+ - | Addition; subtraction.
<< >> | Bitwise left shift; bitwise right shift.
< <= > >= | Less than; less than or equal to; greater than; greater than or equal to.
== != | Equality; inequality (both evaluated left to right).
& | Bitwise AND.
^ | Bitwise exclusive OR.
| | Bitwise OR.
&& | Logical AND (short-circuit).
|| | Logical OR (short-circuit).
?: | Inline conditional evaluation.
= += -= | Assignment.
*= /= %= |
< <= > >= |
&= ^= |= |
, | Sequential expression evaluation.

[a] In ksh93, the ** operator is right associative. In bash versions prior to 3.1, it is left associative. It will be changed to right associative starting with version 3.1.

6.6.2. Built-in Mathematical Functions (ksh93 only)

ksh93 provides access to the standard set of mathematical functions. They are called using C function call syntax.

Name | Function | Name | Function
abs | Absolute value | hypot | Euclidean distance
acos | Arc cosine | int | Integer part of floating-point number
asin | Arc sine | log | Natural logarithm
atan | Arc tangent | pow | Exponentiation (xy)
atan2 | Arc tangent of two variables | sin | Sine
cos | Cosine | sinh | Hyperbolic sine
cosh | Hyperbolic cosine | sqrt | Square root
exp | Exponential (ex) | tan | Tangent
fmod | Floating-point remainder | tanh | Hyperbolic tangent

6.6.3. Examples

See the let command for more information and examples:

    let "count=0" "i = i + 1"     Assign i and count
    let "num % 2"     Test for an even number
    (( percent >= 0 && percent <= 100 ))      Test the range of a value


Section 6.7. Command History

6.7. Command History

Both shells let you display or modify previous commands. Commands in the history list can be modified using:

  • Line-edit mode

  • The fc and hist commands

Bash also supports a command-history mechanism very similar to that of the C shell. Because the interactive line-editing features are considerably superior, and because Bash's command history is almost identical to that of the C shell, we have chosen not to cover those features here. See the Bash manpage for more information.

6.7.1. Line-Edit Mode

Line-edit mode emulates many features of the vi and emacs editors. The history list is treated like a file. When the editor is invoked, you type editing keystrokes to move to the command line you want to execute. You can also change the line before executing it. When you're ready to issue the command, press the Enter key.

In ksh, line-edit mode can be started in several ways. For example, these are equivalent:

    $ VISUAL=vi
    $ EDITOR=vi
    $ set -o vi        Overrides value of VISUAL or EDITOR

For Bash, you must use either set -o vi or set -o emacs; assignment to the VISUAL or EDITOR variables has no effect.

Note that vi starts in input mode; to type a vi command, press the Escape key first.

Bash also provides a csh-style command-line editing mechanism, which we don't cover because the built-in vi and Emacs editing modes are easier to use.

6.7.1.1 Common editing keystrokes

vi | emacs | Result
k | Ctrl-P | Get previous command.
j | Ctrl-N | Get next command.
/string | Ctrl-R string | Get previous command containing string.
h | Ctrl-B | Move back one character.
l | Ctrl-F | Move forward one character.
b | ESC-B | Move back one word.
w | ESC-F | Move forward one word.
X | DEL | Delete previous character.
x | Ctrl-D | Delete character under cursor.
dw | ESC-D | Delete word forward.
db | ESC-H | Delete word backward.
xp | Ctrl-R | Transpose two characters.

6.7.2. The fc and hist Commands

"fc" stands for either "find command" or "fix command," since it does both jobs. Use fc -l to list history commands and fc -e to edit them. See the fc entry in the later section See Built-in Commands (Bash and Korn Shells) for more information.

In ksh93, the fc command has been renamed hist, and alias fc=hist is predefined.

6.7.2.1 Examples
    $ history        List the last 16 commands
    $ fc -l 20 30           List commands 20 through 30
    $ fc -l -5       List the last five commands
    $ fc -l cat      List all commands since the last command beginning with cat
    $ fc -l 50       List all commands since command 50
    $ fc -ln 5 > doit       Save command 5 to file doit
    $ fc -e vi 5 20         Edit commands 5 through 20 using vi
    $ fc -e emacs           Edit previous command using emacs

The following only work in the Korn shell, which predefines the r alias:

    $ r            Reexecute previous command
    $ r cat          Reexecute last cat command
    $ r doc=Doc      Substitute, then reexecute last command
    $ r chap=doc c     Reexecute last command that begins with c, but change string chap
                                         to doc

For both shells, the interactive line editing is easier to use than fc, since you can move up and down in the saved command history using your favorite editor commands (as long as your favorite editor is either vi or Emacs!). Current versions of both shells also let you use the Up and Down arrow keys to traverse the command history.

6.7.3. Programmable Completion (Bash only)

Bash and the readline library provide completion facilities, whereby you can type part of a command name, press the Tab key, and have Bash fill in part or all of the rest of the command or filename. Programmable completion lets you, as a shell programmer, write code to customize the list of possible completions that Bash will present for a particular, partially entered word. This is accomplished through the combination of several facilities:

  • The complete command allows you provide a completion specification, or compspec, for individual commands. You specify, via various options, how to tailor the list of possible completions for the particular command. This is simple, but adequate for many needs. (See the complete entry in the section See Built-in Commands (Bash and Korn Shells)," later in this chapter.)

  • For more flexibility, you may use complete -F funcname command. This tells Bash to call funcname to provide the list of completions for command. You write the funcname function.

  • Within the code for a -F function, the COMP* shell variables provide information about the current command line. COMPREPLY is an array into which the function places the final list of completion results.

  • Also within the code for a -F function, you may use the compgen command to generate is a list of results, such as "usernames that begin with a" or "all set variables." The intent is that such results would be used with an array assignment:

        ...
    COMPREPLY=( $( compgen options arguments ) )
    ...

Compspecs may be associated with either a full pathname for a command or, more commonly, with an unadorned command name (/usr/bin/man versus plain man). Completions are attempted in the following order, based on the options provided to the complete command:

  1. Bash first identifies the command. If a pathname is used, Bash looks to see if a compspec exists for the full pathname. Otherwise, it sets the the command name to the last component of the pathname, and searches for a compspec for the command name.

  2. If a compspec exists, Bash uses it. If not, Bash falls back to the default built-in completions.

  3. Bash performs the action indicated by the compspec to generate a list of possible matches. Of this list, only those that have the word being completed as a prefix are used for the list of possible completions. For the -d and -f options, the variable FIGNORE is used to filter out undesirable matches.

  4. Bash generates filenames as specified by the -G option. GLOBIGNORE is not used to filter the results, but FIGNORE is.

  5. Bash processes the argument string provided to -W. The string is split using the characters in $IFS. The resulting list provides the candidates for completion. This is often used to provide a list of options that a command accepts.

  6. Bash runs functions and commands as specified by the -F and -C options. For both, Bash sets COMP_LINE and COMP_POINT as described previously. For a shell function, COMP_WORDS and COMP_CWORD are also set.

    Also for both, $1 is the name of the command whose arguments are being completed, $2 is the word being completed, and $3 is the word in front of the word being completed. Bash does not filter the results of the command or function.

    1. Functions named with -F are run first. The function should set the COMPREPLY array to the list of possible completions. Bash retrieves the list from there.

    2. Commands provided with -C are run next, in an environment equivalent to command substitution. The command should print the list of possible completions, one per line. An embedded newline should be escaped with a backslash.

  7. Once the list is generated, Bash filters the results according to the -X option. The argument to -X is a pattern specifying files to exclude. By prefixing the pattern with a !, the sense is reversed, and the pattern instead specifies that only matching files should be retained in the list.

    An & in the pattern is replaced with the text of the word being completed. Use \& to produce a literal &.

  8. Finally, Bash prepends or appends any prefixes or suffixes supplied with -P or -S options.

  9. In the case that no matches were generated, if -o dirnames was used, Bash will attempt directory name completion.

  10. On the other hand, if -o plusdirs was provided, Bash adds the result of directory completion to the previously generated list.

  11. Normally, when a compspec is provided, Bash's default completions are not attempted, nor are the readline library's default filename completions.

    1. If the compspec produces no results and -o bashdefault was provided, then Bash will attempt its default completions.

    2. If neither the compspec, nor the Bash default completions with -o bashdefault produced any results, and -o default was provided, then Bash has the readline library attempt its filename completions.

Ian Macdonald has collected a large set of useful compspecs, often distributed as the file /etc/bash_completion. If your system does not have it, one location for downloading it is http://www.dreamind.de/files/bash-stuff/bash_completion. It is worth retrieving and reviewing.

6.7.3.1 Examples

Restrict files for the C compiler to C, C++ and assembler source files, and relocatable object files:

    complete -f -X '!*.[Ccos]' gcc cc

For the man command, restrict expansions to things that have manpages:

    # Simple example of programmable completion for manual pages.
    # A more elaborate example appears in the bash_completion file.
    # Assumes   man [num] command   command syntax.

    shopt -s extglob             Enable extended pattern matching
    _man (  ) {
        local dir mandir=/usr/share/man     Local variables

        COMPREPLY=(  )            Clear reply list
        if [[ ${COMP_WORDS[1]} = +([0-9]) ]]       Section number provided
        then
            # section provided: man 3 foo
            dir=$mandir/man${COMP_WORDS[COMP_CWORD-1]}    Look in that directory
        else
            # no section, default to commands
            dir=$mandir/'man[18]'           Look in command directories
        fi
        COMPREPLY=( $( find $dir -type f |         Generate raw file list
                sed 's;..*/;;' |            Remove leading directories
                sed 's/\.[0-9].*$//' |             Remove trailing suffixes
                grep "^${COMP_WORDS[$COMP_CWORD]}" |      Keep those that match
                                             given prefix
                sort          Sort final list
                ) )
    }
    complete -F _man man               Associate function with command


Section 6.8. Job Control

6.8. Job Control

Job control lets you place foreground jobs in the background, bring background jobs to the foreground, or suspend (temporarily stop) running jobs. All modern Unix systems, including Linux and BSD systems, support job control; thus the job-control features are automatically enabled. Many job-control commands take a jobID as an argument. This argument can be specified as follows:

%n

Job number n.

%s

Job whose command line starts with string s.

%?s

Job whose command line contains string s.

%%

Current job.

%+

Current job (same as above).

%-

Previous job.

Both shells provide the following job-control commands. For more information on these commands, see the Built-in Commands (Bash and Korn Shells)," later in this chapter.

bg

Put a job in the background.

fg

Put a job in the foreground.

jobs

List active jobs.

kill

Terminate a job.

stty tostop

Stop background jobs if they try to send output to the terminal. (Note that stty is not a built-in command.)

suspend

Suspend a job-control shell (such as one created by su).

wait

Wait for background jobs to finish.

Ctrl-Z

Suspend a foreground job. Then use bg or fg. (Your terminal may use something other than Ctrl-Z as the suspend character.)


Section 6.9. Command Execution

6.9. Command Execution

When you type a command to Bash or ksh93, they look in the following places until they find a match:

  1. Keywords such as if and for.

  2. Aliases. You can't define an alias whose name is a shell keyword, but you can define an alias that expands to a keyword, e.g., alias aslongas=while. (Bash, when not in POSIX mode, does allow you to define an alias for a shell keyword.)

  3. Special built-ins like break and continue. The list of POSIX special built-ins is . (dot), :, break, continue, eval, exec, exit, export, readonly, return, set, shift, times, trap, and unset. The Korn shell adds alias, login, typeset, and unalias, while Bash adds source.

  4. Functions. When not in POSIX mode, Bash finds functions before built-in commands.

  5. Nonspecial built-ins like cd and test.

  6. Scripts and executable programs, for which the shell searches in the directories listed in the PATH environment variable.

The distinction between "special" built-in commands and nonspecial ones comes from POSIX. This distinction, combined with the command command, makes it possible to write functions that override shell built-ins, such as cd. For example:

    cd (  ) {         Shell function, found before built-in cd
        command cd "$@"    Use real cd to change directory
        echo now in $PWD          Other stuff we want to do
    }

In ksh88, the search order is different; all built-ins are found before shell functions. Thus you have to do more work to override a built-in command with a function. You do so using a combination of functions and aliases:

    _cd (  ) {        Shell function, note leading underscore
        cd "$@"            Use real cd to change directory
        echo now in $PWD          Other stuff we want to do
    }
    alias cd=_cd           Alias found first


Section 6.10. Restricted Shells

6.10. Restricted Shells

A restricted shell is one that disallows certain actions, such as changing directory, setting PATH, or running commands whose names contain a / character.

The original V7 Bourne shell had an undocumented restricted mode. Later versions of the Bourne shell clarified the code and documented the facility. Today, both Bash and the Korn shell supply a restricted mode, but with differing sets of items that get restricted. (See the respective manual pages for the details.)

Shell scripts can still be run, since in that case the restricted shell calls the unrestricted version of the shell to run the script. This includes /etc/profile, $HOME/.profile, and other startup files.

Restricted shells are not used much in practice, as they are difficult to set up correctly.


Section 6.11. Built-in Commands (Bash and Korn Shells)

6.11. Built-in Commands (Bash and Korn Shells)

Examples to be entered as a command line are shown with the $ prompt. Otherwise, examples should be treated as code fragments that might be included in a shell script. For convenience, some of the reserved words used by multiline commands are also included.

!
    ! pipeline

Not ksh88. Negate the sense of a pipeline. Returns an exit status of 0 if the pipeline exited nonzero, and an exit status of 1 if the pipeline exited zero. Typically used in if and while statements.

Example

This code prints a message if user jane is not logged on:

    if ! who | grep jane > /dev/null
    then
            echo jane is not currently logged on
    fi

#
    #

Ignore all text that follows on the same line. # is used in shell scripts as the comment character and is not really a command.

#!shell
    #!shell [option]

Used as the first line of a script to invoke the named shell. Anything given on the rest of the line is passed as a single argument to the named shell. This feature is typically implemented by the kernel, but may not be supported on some older systems. Some systems have a limit of approximately 32 characters on the maximum length of shell. For example:

    #!/bin/sh

:
    :

Null command. Returns an exit status of 0. The line is still processed for side effects, such as variable and command substitutions, or I/O redirection. See the following Example and the Example under case.

Example

Check whether someone is logged in:

    if who | grep $1 > /dev/null
    then :   # Do nothing if user is found
    else echo "User $1 is not logged in"
    fi

.
    . file [arguments]

Read and execute lines in file. file does not have to be executable, but must reside in a directory searched by PATH. The arguments are stored in the positional parameters. If Bash is not in POSIX mode and file is not found in PATH, it will look in the current directory for file.

[[ ]]
    [[ expression ]]

Same as test expression or [ expression ], except that [[ ]] allows additional operators. Word splitting and filename expansion are disabled. Note that the brackets ([ ]) are typed literally and that they must be surrounded by whitespace.

Additional Operators

&&

Logical AND of test expressions (short circuit).

||

Logical OR of test expressions (short circuit).

<

First string is lexically "less than" the second.

>

First string is lexically "greater than" the second.

alias
    alias [options] [name[='cmd']]

Assign a shorthand name as a synonym for cmd. If ='cmd' is omitted, print the alias for name ; if name is also omitted, print all aliases. If the alias value contains a trailing space, the next word on the command line also becomes a candidate for alias expansion. See also unalias.

These aliases are built into ksh88. Some use names of existing Bourne shell or C shell commands:

    autoload='typeset -fu'
    false='let 0'
    functions='typeset -f'
    hash='alias -t'
    history='fc -l'
    integer='typeset -i'
    nohup='nohup '
    r='fc -e -'
    true=':'
    type='whence -v'

The following aliases are built into ksh93:

    autoload='typeset -fu'
    command='command '
    fc='hist'
    float='typeset -E'
    functions='typeset -f'
    hash='alias -t --'
    history='hist -l'
    integer='typeset -i'
    nameref='typeset -n'
    nohup='nohup '
    r='hist -s'
    redirect='command exec'
    stop='kill -s STOP'
    times='{ {time;} 2>&1;}'
    type='whence -v'

Options

-p

Print the word alias before each alias. Not ksh88.

-t

Create a tracked alias for a Unix command name. The Korn shell remembers the full pathname of the command, allowing it to be found more quickly and to be issued from any directory. If no name is supplied, current tracked aliases are listed. Tracked aliases are similar to hashed commands in Bash. Korn shell only. ksh93 always does alias tracking.

-x

Export the alias; it can now be used in shell scripts and other subshells. If no name is supplied, current exported aliases are listed. Korn shell only. ksh93 accepts this option but ignores it.

Example

    alias dir='echo ${PWD##*/}'

autoload
    autoload [functions]

Korn shell alias for typeset -fu. Load (define) the functions only when they are first used.

bind
    bind [-m map] [options]
    bind [-m map] [-q function] [-r sequence] [-u function]
    bind [-m map] -f file
    bind [-m map] -x sequence:command
    bind [-m map] sequence:function
    bind readline-command

Bash only. Manage the readline library. Non-option arguments have the same form as in a .inputrc file.

Options

-f file

Read key bindings from file.

-l

List the names of all the readline functions.

-m map

Use map as the keymap. Available keymaps are: emacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move, vi-command, and vi-insert. vi is the same as vi-command, and emacs is the same emacs-standard.

-p

Print the current readline bindings such that they can be reread from a .inputrc file.

-P

Print the current readline bindings.

-q function

Query which keys invoke the readline function function.

-r sequence

Remove the binding for key sequence sequence.

-s

Print the current readline key sequence and macro bindings such that they can be reread from a .inputrc file.

-S

Print the current readline key sequence and macro bindings.

-u function

Unbind all keys that invoke the readline function function.

-v

Print the current readline variables such that they can be reread from a .inputrc file.

-V

Print the current readline variables.

-x sequence:command

Execute the shell command command whenever sequence is entered.

bg
    bg [jobIDs]

Put current job or jobIDs in the background. See the earlier section Job Control."

break
    break [n]

Exit from a for, while, select, or until loop (or break out of n loops).

builtin
    builtin command [ arguments ... ]

Bash version. Run the shell built-in command command with the given arguments. This allows you to bypass any functions that redefine a built-in command's name. The command command is more portable.

Example

This function lets you do your own tasks when you change directory:

    cd (  ) {

        builtin cd "$@"      Actually change directory

        pwd           Report location

    }

builtin
    builtin [ -ds ] [ -f library ] [ name ... ]

ksh93 version. This command allows you to load new built-in commands into the shell at runtime from shared library files.

If no arguments are given, builtin prints all the built-in command names. With arguments, builtin adds each name as a new built-in command (like cd or pwd). If the name contains a slash, the newly added built-in version is used only if a path search would otherwise have found a command of the same name. (This allows replacement of system commands with faster, built-in versions.) Otherwise, the built-in command is always found.

Options

-d

Delete the built-in command name.

-f

Load new built-in command from library.

-s

Only print "special" built-ins (those designated as special by POSIX).

case
case value in
 pattern1) cmds1;;
 pattern2) cmds2;;
 .
 .
 .
esac

Execute the first set of commands (cmds1) if value matches pattern1, execute the second set of commands (cmds2) if value matches pattern2, etc. Be sure the last command in each set ends with ;;. value is typically a positional parameter or other shell variable. cmds are typically Unix commands, shell programming commands, or variable assignments. Patterns can use file-generation metacharacters. Multiple patterns (separated by |) can be specified on the same line; in this case, the associated cmds are executed whenever value matches any of these patterns. See the Examples here and under eval.

The shells allow pattern to be preceded by an optional open parenthesis, as in (pattern). In Bash and ksh88, it's necessary for balancing parentheses inside a $( ) construct.

The Korn shell allows a case to end with ;& instead of ;;. In such cases, control "falls through" to the group of statements for the next pattern.

Examples

Check first command-line argument and take appropriate action:

    case $1 in     # Match the first arg

        no|yes) response=1;;

        -[tT])  table=TRUE;;

        *)      echo "unknown option"; exit 1;;
    esac

Read user-supplied lines until user exits:

    while :        # Null command; always true

    do

       printf "Type . to finish =  => "

       read line

       case "$line" in

          .) echo "Message done"

             break ;;

          *) echo "$line" >> $message ;;

       esac

    done

caller
    caller [expression]

Bash only. Print the line number and source file name of the current function call or dot file. With nonzero expression, prints that element from the call stack. The most recent is zero. This command is for use by the Bash debugger.

cd
    cd [-LP] [dir]
    cd [-LP] [-]
    cd [-LP] [old new]

With no arguments, change to home directory of user. Otherwise, change working directory to dir. If dir is a relative pathname but is not in the current directory, the CDPATH variable is searched. A directory of - stands for the previous directory. The last syntax is specific to the Korn shell. It modifies the current directory name by replacing string old with new and then switches to the resulting directory.

Options

-L

Use the logical path (what the user typed, including any symbolic links) for cd .. and the value of PWD. This is the default.

-P

Use the actual filesystem physical path for cd .. and the value of PWD.

Example

    $ pwd

    /var/spool/cron

    $ cd cron uucp     Ksh: cd prints the new directory

    /var/spool/uucp

command
    command [-pvV] name [arg ...]

Not ksh88. Without -v or -V, execute name with given arguments. This command bypasses any aliases or functions that may be defined for name. When used with a special built-in, it prevents the built-in from exiting the script if it fails.

Options

-p

Use a predefined, default search path, not the current value of PATH.

-v

Print a description of how the shell interprets name.

-V

Print a more verbose description of how the shell interprets name.

Example

Create an alias for rm that will get the system's version, and run it with the -i option:

    $ alias 'rm=command -p rm -i'

compgen
    compgen [options] [string]

Bash only. Generate possible completions for string according to the options. Options are those accepted by complete, except for -p and -r. For more information, see the entry for complete.

complete
    complete [options] command ...

Bash only. Specify the way to complete arguments for each command. This is discussed in See Programmable Completion (Bash only)," earlier in the chapter.

Options

-a

Same as -A alias.

-A type

Use type to specify a list of possible completions. The type may be one of the following.

alias

Alias names.

arrayvar

Array variable names.

binding

Bindings from the readline library.

builtin

Shell built-in command names.

directory

Directory names.

disabled

Names of disabled shell built-in commands.

enabled

Names of enabled shell built-in commands.

function

Names of shell functions.

group

Group names.

helptopic

Help topics as allowed by the help built-in command.

hostname

Hostnames, as found in the file named by $HOSTFILE.

job

Job names.

keyword

Shell reserved keywords.

running

Names of running jobs.

service

Service names (from /etc/services).

setopt

Valid arguments for set -o.

shopt

Valid option names for the shopt built-in command.

signal

Signal names.

stopped

Names of stopped jobs.

user

Usernames.

variable

Shell variable names.

-b

Same as -A builtin.

-c

Same as -A command.

-C command

Run command in a subshell and use its output as the list of completions.

-d

Same as -A directory.

-e

Same as -A export.

-f

Same as -A file.

-F function

Run shell function function in the current shell. Upon its return, retrieve the list of completions from the COMPREPLY array.

-g

Same as -A group.

-G pattern

Expand pattern to generate completions.

-j

Same as -A job.

-k

Same as -A keyword.

-o option

Control the behavior of the completion specification. The value for option is one of the following.

bashdefault

Fall back to the normal Bash completions if no matches are produced.

default

Use the default readline completions if no matches are produced.

dirnames

Do directory name completion if no matches are produced.

filenames

Inform the readline library that the intended output is filenames, so that the library can do any filename-specific processing, such as adding a trailing slash for directories or removing trailing spaces.

nospace

Inform the readline library that it should not append a space to words completed at the end of a line.

plusdirs

Attempt directory completion and add any results to the list of completions already generated.

-p

With no commands, print all completion settings in a way that can be reread.

-P prefix

The prefix is added to each resulting string as a prefix after all the other options have been applied.

-r

Remove the completion settings for the given commands, or all settings if no commands.

-s

Save as -A service.

-S suffix

The suffix is added to each resulting string as a suffix after all the other options have been applied.

-u

Same as -A user.

-v

Same as -A variable.

-W wordlist

Split wordlist (a single shell word) using $IFS. The generated list contains the members of the split list that matched the word being completed. Each member is expanded using brace expansion, tilde expansion, parameter and variable expansion, command substitution, and arithmetic expansion. Shell quoting is respected.

-X pattern

Exclude filenames matching pattern from the filename completion list. With a leading !, the sense is reversed, and only filenames matching pattern are retained.

continue
    continue [n]

Skip remaining commands in a for, while, select, or until loop, resuming with the next iteration of the loop (or skipping n loops).

declare
    declare [options] [name[=value]]

Bash only. Declare variables and manage their attributes. In function bodies, variables are local, as if declared with the local command.

Options

-a

Each name is an array.

-f

Each name is a function.

-F

For functions, print just the functions' name and attributes, not the function definition (body).

-i

Each variable is an integer; in an assignment, the value is evaluated as an arithmetic expression.

-p

With no names, print all variables and their values. With names, print the names, attributes, and values of the given variables. This option causes all other options to be ignored.

-r

Mark names as read-only. Subsequent assignments will fail.

-t

Apply the trace attribute to each name. Traced functions inherit the DEBUG trap. This attribute has no meaning for variables.

-x

Mark names for export into the environment of child processes.

With a + instead of a -, the given attribute is disabled. With no variable names, all variables having the given attribute(s) are printed in a form that can be reread as input to the shell.

Examples

    $ declare -i val      Make val an integer
        $ val=4+7         Evaluate value
        $ echo $val       Show result
        11

    $ declare -r z=42        Make z read-only
        $ z=31            Try to assign to it
        bash: z: readonly variable     Assignment fails
        $ echo $z
        42

        $ declare -p val z       Show attributes and values
        declare -i val="11"
        declare -r z="42"

dirs
    dirs [-clpv] [+n] [-n]

Bash only. Print the directory stack, which is managed with pushd and popd.

Options

+n

Print the nth entry from the left; first entry is zero.

-n

Print the nth entry from the right; first entry is zero.

-c

Remove all entries from (clear) the directory stack.

-l

Produce a longer listing, one that does not replace $HOME with ~.

-p

Print the directory stack, one entry per line.

-v

Print the directory stack, one entry per line, with each entry preceded by its index in the stack.

disown
    disown [-ahr] [job ...]

Bash version. Remove job from the list of jobs managed by Bash.

Options

-a

Remove all jobs. With -h, mark all jobs.

-h

Instead of removing jobs from the list of known jobs, mark them to not receive SIGHUP when Bash exits.

-r

With no jobs, remove (or mark) only running jobs.

disown
    disown [job ...]

ksh93 version. When a login shell exits, do not send a SIGHUP to the given jobs. If no jobs are listed, no background jobs will receive SIGHUP.

do
    do

Reserved word that precedes the command sequence in a for, while, until, or select statement.

done
    done

Reserved word that ends a for, while, until, or select statement.

echo
    echo [-eEn] [string]

Bash version, built into the shell. Write string to standard output. (See also echo in Chapter 3.)

Options

-e

Enable interpretation of the following escape sequences, which must be quoted (or escaped with a \) to prevent interpretation by the shell:

\a

Alert (ASCII BEL).

\b

Backspace.

\c

Suppress the terminating newline (same as -n).

\e

ASCII Escape character.

\f

Formfeed.

\n

Newline.

\r

Carriage return.

\t

Tab character.

\v

Vertical-tab character.

\\

Backslash.

\0nnn

ASCII character represented by octal number nnn, where nnn is zero, one, two, or three digits and is preceded by a 0.

\nnn

ASCII character represented by octal number nnn, where nnn is one, two, or three digits.

\xHH

ASCII character represented by hexadecimal number HH, where HH is one or two hexadecimal digits.

-E

Do not interpret escape sequences, even on systems where the default behavior of the built-in echo is to interpret them.

-n

Do not print the terminating newline.

Examples

    $ echo "testing printer" | lp
    $ echo "Warning: ringing bell \a"

echo
    echo [-n] [string]

Korn shell version. Write string to standard output; if -n is specified, the output is not terminated by a newline. If no string is supplied, echo a newline.

The Korn shell's echo, even though it is built into the shell, emulates the system's version of echo. Thus, if the version found by a path search supports -n, the built-in version does, too. Similarly, if the external version supports the escape sequences described below, the built-in version does, too; otherwise it does not.[*] (See also echo in Chapter 3.) echo understands special escape characters, which must be quoted (or escaped with a \) to prevent interpretation by the shell:

[*] The situation with echo is a mess; consider using printf instead.

\a

Alert (ASCII BEL).

\b

Backspace.

\c

Suppress the terminating newline (same as -n).

\f

Formfeed.

\n

Newline.

\r

Carriage return.

\t

Tab character.

\v

Vertical-tab character.

\\

Backslash.

\0nnn

ASCII character represented by octal number nnn, where nnn is one, two, or three digits and is preceded by a 0.

enable
    enable [-adnps] [-f file] [command ...]

Bash only. Enable or disable shell built-in commands. Disabling a built-in lets you use an external version of a command that would otherwise use a built-in version, such as echo or test.

Options

-a

For use with -p, print information about all built-in commands, disabled and enabled.

-d

Remove (delete) a built-in previously loaded with -f.

-f file

Load a new built-in command command from the shared library file file.

-n

Disable the named built-in commands.

-p

Print a list of enabled built-in commands.

-s

Print only the POSIX special built-in commands. When combined with -f, the new built-in command becomes a POSIX special built-in.

esac
    esac

Reserved word that ends a case statement.

eval
    eval args

Typically, eval is used in shell scripts, and args is a line of code that contains shell variables. eval forces variable expansion to happen first and then runs the resulting command. This "double-scanning" is useful any time shell variables contain input/output redirection symbols, aliases, or other shell variables. (For example, redirection normally happens before variable expansion, so a variable containing redirection symbols must be expanded first using eval; otherwise, the redirection symbols remain uninterpreted.)

Example

This fragment of a shell script shows how eval constructs a command that is interpreted in the right order:

    for option
    do
        case "$option" in   Define where output goes
           save) out=' > $newfile' ;;
           show) out=' | more' ;;
        esac
     done

     eval sort $file $out

exec
    exec [command args ...]
    exec [-a name] [-cl] [command args ... ]

Execute command in place of the current process (instead of creating a new process). exec is also useful for opening, closing, or copying file descriptors. The second form is for ksh93 and Bash.

Options

-a

Use name for the value of argv[0].

-c

Clear the environment before executing the program.

-l

Place a minus sign at the front of argv[0], just as login(1) does. Bash only.

Examples

    trap 'exec 2>&-' 0        Close standard error when
                             shell script exits (signal 0)

    $ exec /bin/csh      Replace shell with C shell
    $ exec < infile       Reassign standard input to infile

exit
    exit [n]

Exit a shell script with status n (e.g., exit 1). n can be 0 (success) or nonzero (failure). If n is not given, exit status is that of the most recent command. exit can be issued at the command line to close a window (log out). Exit statuses can range in value from 0 to 255.

Example

    if [ $# -eq 0 ]
    then
       echo "Usage: $0 [-c] [-d] file(s)" 1>&2
       exit 1               # Error status
    fi

export
    export [variables]
    export [name=[value] ...]
    export -p
    export [-fn] [name=[value] ...]

Pass (export) the value of one or more shell variables, giving global meaning to the variables (which are local by default). For example, a variable defined in one shell script must be exported if its value is used in other programs called by the script. If no variables are given, export lists the variables exported by the current shell. The second form is the POSIX version, which is similar to the first form, except that you can set a variable name to a value before exporting it. The third form is not available in ksh88. The fourth form is specific to Bash.

Options

-f

Names refer to functions; the functions are exported in the environment. Bash only.

-n

Remove the named variables or functions from the environment. Bash only.

-p

Print export before printing the names and values of exported variables. This allows saving a list of exported variables for rereading later.

Example

In the original Bourne shell, you would type:

    TERM=vt100
    export TERM

In Bash and the Korn shell, you could type this instead:

    export TERM=vt100

false
    false

ksh88 alias for let 0. Built-in command in Bash and ksh93 that exits with a false return value.

fc
    fc [options] [first [last]]
    fc -e - [old=new] [command]
    fc -s [old=new] [command]

ksh88 and Bash. Display or edit commands in the history list. (Use only one of -e, -l or -s.) first and last are numbers or strings specifying the range of commands to display or edit. If last is omitted, fc applies to a single command (specified by first). If both first and last are omitted, fc edits the previous command or lists the last 16. The second form of fc takes a history command, replaces old with new, and executes the modified command. If no strings are specified, command is just reexecuted. If no command is given either, the previous command is reexecuted. command is a number or string like first. See the examples in the earlier section Command History." The third form, available in Bash and ksh93, is equivalent to the second form.

Options

-e [editor]

Invoke editor to edit the specified history commands. The default editor is set by the shell variable FCEDIT. If that variable is not set, the default is /bin/ed. (Bash defaults to vi; Version 3.1 and newer will default to /bin/ed when in POSIX mode.) Bash tries FCEDIT, then EDITOR, and then /bin/ed.

-e -

Execute (or redo) a history command; refer to second syntax line above.

-l

List the specified command or range of commands, or list the last 16.

-n

Suppress command numbering from the -l listing.

-r

Reverse the order of the -l listing.

-s

Equivalent to -e -. Not in ksh88.

fc
    fc

ksh93 alias for hist.

fg
    fg [jobIDs]

Bring current job or jobIDs to the foreground. See the earlier section Job Control."

fi
    fi

Reserved word that ends an if statement. (Don't forget to use it!)

for
    for x [in list]
    do
     commands
    done

For variable x (in optional list of values) do commands. If in list is omitted, "$@" (the positional parameters) is assumed.

Examples

Paginate files specified on the command line; save each result:

    for file; do
         pr $file > $file.tmp
    done

Search chapters for a list of words (like fgrep -f):

    for item in `cat program_list`
    do
         echo "Checking chapters for"
         echo "references to program $item..."
         grep -c "$item.[co]" chap*
    done

Extract a one-word title from each file and use as new filename:

    for file
    do
         name=`sed -n 's/NAME: //p' $file`
         mv $file $name
    done

for
    for ((init; cond; incr))
    do
     commands
    done

Bash and ksh93. Arithmetic for loop, similar to C's. Evaluate init. While cond is true, execute the body of the loop. Evaluate incr before retesting cond. Any one of the expressions may be omitted; a missing cond is treated as being true.

Examples

Search for a phrase in each odd chapter:

    for ((x=1; x <= 20; x += 2))
    do
            grep $1 chap$x
    done

function
    function name { commands; }
    function name (  ) { commands; }

Define name as a shell function. See the description of semantic issues in the earlier section Functions." The first form is for the Korn shell, although it may also be used with Bash. The second form is specific to Bash. Bash does not give different semantics to functions declared differently; all Bash functions behave the same way.

Example

Define a function to count files:

    $ function fcount {
    >    ls | wc -l
    > }

functions
    functions

Korn shell alias for typeset -f. (Note the "s" in the name; function is a Korn shell keyword.) See typeset later in this listing.

getconf
    getconf [name [path]]

ksh93 only. Retrieve the values for parameters that can vary across systems. name is the parameter to retrieve; path is a filename to test for parameters that can vary on different filesystem types.

The parameters are defined by the POSIX 1003.1 standard. See the entry for getconf in Chapter 3.

Example

Print the maximum value that can be held in a C int:

    $ getconf INT_MAX
    2147483647

getopts
    getopts [-a name] string name [args]

Process command-line arguments (or args, if specified) and check for legal options. getopts is used in shell-script loops and is intended to ensure standard syntax for command-line options. Standard syntax dictates that command-line options begin with a -. Options can be stacked: i.e., consecutive letters can follow a single -. End processing of options by specifying -- on the command line. string contains the option letters to be recognized by getopts when running the shell script. Valid options are processed in turn and stored in the shell variable name. If an option is followed by a colon, the option must be followed by one or more arguments. (Multiple arguments must be given to the command as one shell word. This is done by quoting the arguments or separating them with commas. The application must be written to expect multiple arguments in this format.) getopts uses the shell variables OPTARG and OPTIND. The Bash version also uses OPTERR.

Option

-a

Use name in error messages about invalid options. ksh93 only.

hash
    hash [-dlrt] [-p file] [commands]

Bash version. As the shell finds commands along the search path ($PATH), it remembers the found location in an internal hash table. The next time you enter a command, the shell uses the value stored in its hash table.

With no arguments, hash lists the current hashed commands. The display shows hits (the number of times the command is called by the shell) and the command name.

With commands, the shell adds those commands to the hash table.

Options

-d

Remove (delete) just the specified commands from the hash table.

-l

Produce output in a format that can be reread to rebuild the hash table.

-p file

Associate file with command in the hash table.

-r

Remove all commands from the hash table.

-t

With one name, print the full pathname of the command. With more than one name, print the name and the full path, in two columns.

Besides the -r option, the hash table is also cleared when PATH is assigned. Use PATH=$PATH to clear the hash table without affecting your search path. This is most useful if you have installed a new version of a command in a directory that is earlier in $PATH than the current version of the command.

hash
    hash

Korn shell alias for alias -t (alias -t -- in ksh93). Approximates the Bourne shell's hash.

help
    help [-s] [pattern]

Bash only. Print usage information on standard output for each command that matches pattern. The information includes descriptions of each command's options. With the -s option, print only brief usage information.

Examples

    $ help -s cd          Short help
    cd: cd [-L|-P] [dir]

    $ help true           Full help
    true: true
        Return a successful result.

hist
    hist [options] [first [last]]
    hist -s [old=new] [command]

ksh93 only. Display or edit commands in the history list. (Use only one of -l or -s.) first and last are numbers or strings specifying the range of commands to display or edit. If last is omitted, hist applies to a single command (specified by first). If both first and last are omitted, hist edits the previous command or lists the last 16. The second form of hist takes a history command, replaces old with new, and executes the modified command. If no strings are specified, command is just reexecuted. If no command is given either, the previous command is reexecuted. command is a number or string like first. See the examples in the earlier section Command History."

Options

-e [editor]

Invoke editor to edit the specified history commands. The default editor is set by the shell variable HISTEDIT. If that variable is not set, FCEDIT is used. If neither is set, the default is /bin/ed.

-l

List the specified command or range of commands, or list the last 16.

-n

Suppress command numbering from the -l listing.

-N n

Start with the command n commands before the current one.

-r

Reverse the order of the -l listing.

-s

Execute (or redo) a history command; refer to second syntax line above.

history
    history [count]
    history [options]

Bash version. Print commands in the history list or manage the history file. With no options or arguments, display the history list with command numbers. With a count argument, print only that many of the most recent commands.

Options

-a

Append new history lines (those executed since the beginning of the session) to the history file.

-c

Clear the history list (remove all entries).

-d position

Delete the history item at position position.

-n

Read unread history lines from the history file into the history list.

-p argument ...

Perform csh-style history expansion on each argument, printing the results to standard output. The results are not saved in the history list.

-r

Read the history file and replace the history list with its contents.

-s argument ...

Store the arguments in the history list, as a single entry.

-w

Write the current history list to the history file, overwriting it entirely.

history
    history

ksh88 alias for fc -l. ksh93 alias for hist -l. Show the last 16 commands.

if
    if condition1then commands1
    [ elif condition2 then commands2 ]
     .
     .
     .
    [ else commands3 ]
    fi

If condition1 is met, do commands1; otherwise, if condition2 is met, do commands2 ; if neither is met, do commands3. Conditions are often specified with the test and [[ ]] commands. See test and [[ ]] for a full list of conditions, and see additional Examples under : and exit.

Examples

Insert a 0 before numbers less than 10:

    if [ $counter -lt 10 ]
    then number=0$counter
    else number=$counter
    fi

Make a directory if it doesn't exist:

    if [ ! -d $dir ]; then
       mkdir $dir
       chmod 775 $dir
    fi

integer
    integer

Korn shell alias for typeset -i. Specify integer variables.

jobs
    jobs [options] [jobIDs]

List all running or stopped jobs, or list those specified by jobIDs. For example, you can check whether a long compilation or text format is still running. Also useful before logging out. See the earlier section Job Control."

Options

-l

List job IDs and process group IDs.

-n

List only jobs whose status changed since last notification.

-p

List process group IDs only.

-r

List running jobs only. Bash only.

-x cmd

Replace each job ID found in cmd with the associated process ID and then execute cmd. Bash only.

kill
    kill [options] IDs

Terminate each specified process ID or job ID. You must own the process or be a privileged user. This built-in command is similar to /usr/bin/kill, described in Chapter 3. See the earlier section Job Control."

Options

-l

List the signal names. (Used by itself.)

-n num

Send the given signal number. Not ksh88.

-s name

Send the given signal name. Not ksh88.

-signal

The signal number (from /usr/include/sys/signal.h) or name (from kill -l). With a signal number of 9, the kill is absolute.

Signals

Signals are defined in /usr/include/sys/signal.h and are listed here without the SIG prefix. The correspondence between signal name and signal number shown in the following table is correct for Linux; many are different on other Unix-style operating systems.

Name | Number | Description
HUP | 1 | Hangup
INT | 2 | Interrupt (usually invoked by user through Ctrl-C)
QUIT | 3 | Quit
ILL | 4 | Illegal instruction
TRAP | 5 | Trace trap
ABRT | 6 | Abort
IOT | 6 | IOT trap
BUS | 7 | Bus error (a type of illegal address access)
FPE | 8 | Floating-point exception (example: division by 0)
KILL | 9 | Kill, unblockable (often used with INT fails to terminate process)
USR1 | 10 | User-defined signal 1
SEGV | 11 | Segmentation violation (a type of illegal address access)
USR2 | 12 | User-defined signal 2
PIPE | 13 | Broken pipe (generated when process on one side of pipe is aborted)
ALRM | 14 | Alarm clock (used for delivering timed alerts from a program)
TERM | 15 | Termination
STKFLT | 16 | Stack fault (a type of illegal address access)
CLD or CHLD | 17 | Child status has changed
CONT | 18 | Continue (issued after STOP or TSTP)
STOP | 19 | Stop, unblockable
TSTP | 20 | Stop (issued at terminal, usually through Ctrl-Z)
TTIN | 21 | Attempt to read from terminal while in background
TTOU | 22 | Unsuccessful attempt to write to terminal while in background
URG | 23 | Urgent condition on socket
XCPU | 24 | CPU usage limit exceeded
XFSZ | 25 | File size limit exceeded
VTALRM | 26 | Virtual alarm clock
PROF | 27 | Profiling alarm clock
WINCH | 28 | Window size change
IO or POLL | 29 | Ready for I/O (used in applications for interrupts)
PWR | 30 | Power failure restart
SYS | 31 | Bad system call

let
    let expressions or
    ((expressions))

Perform arithmetic as specified by one or more expressions. expressions consist of numbers, operators, and shell variables (which don't need a preceding $). Expressions must be quoted if they contain spaces or other special characters. The (( )) form does the quoting for you. For more information and examples, see Arithmetic Expressions," earlier in this chapter. See also expr in Chapter 3.

Examples

Each of these examples adds 1 to variable i:

    i=`expr $i + 1`         All Bourne shells
    let i=i+1        Bash, ksh
    let "i = i + 1"
    (( i = i + 1 ))
    (( i += 1 ))
    (( i++ ))        Bash, ksh93

local
    local [options] [name[=value]]

Bash only. Declares local variables for use inside functions. The options are the same as those accepted by declare; see declare for the full list. It is an error to use local outside a function body.

login
    login [user]

Korn shell only. The shell does an execve(2) of the standard login program, allowing you to replace one login session with another, without having to logout first.

logout
    logout

Bash only. Exit a login shell. The command fails if the current shell is not a login shell.

name ( )
    name (  ) { commands; }

Define name as a function. POSIX syntax. The function definition can be written on one line or across many. Bash and the Korn shell provide the function keyword, alternate forms that work similarly. See the Functions section, earlier in the chapter.

Example

    $ count (  ) {
    > ls | wc -l
    > }

When issued at the command line, count now displays the number of files in the current directory.

nameref
    nameref newvar=oldvar ...

ksh93 alias for typeset -n. See the discussion of indirect variables in the Variables section, earlier in this chapter.

nohup
    nohup command [arguments] &

Don't terminate a command after logout. nohup is a Korn shell alias:

    nohup='nohup '

The embedded space at the end lets nohup interpret the following command as an alias, if needed.

popd
    popd [-n] [+count] [-count]

Bash only. Pop the top directory off the directory stack (as shown by the dirs command), and change to the new top directory, or manage the directory stack.

Options

-n

Don't change to the new top directory; just manipulate the stack.

+count

Remove the item count entries from the left, as shown by dirs. Counting starts at zero. No directory change occurs.

-count

Remove the item count entries from the right, as shown by dirs. Counting starts at zero. No directory change occurs.

print
    print [options] [string ...]

Korn shell only. Display string (on standard output by default). print includes the functions of echo and can be used in its place on most Unix systems.

Options

-

Ignore all subsequent options.

--

Same as -.

-e

Interpret escape sequences in argument strings. (This is the default, anyway.) Use it to undo an earlier -r in the same command line. ksh93 only.

-f format

Print like printf, using format as the format string. Ignores the -n, -r, and -R options. ksh93 only.

-n

Don't end output with a newline.

-p

Send string to the process created by |&, instead of to standard output.

-r

Ignore the escape sequences often used with echo.

-R

Same as -r and ignore subsequent options (except -n).

-s

Send string to the history file.

-u[n]

Send string to file descriptor n (default is 1).

printf
    printf format [val ...]

Not ksh88. Formatted printing, like the ANSI C printf function.

Additional Format Letters

Both Bash and ksh93 accept additional format letters. Bash provides only %b and %q, while ksh93 provides all those in the following list:

%b

Expand escape sequences in strings (e.g., \t to tab, and so on).

%B

The corresponding argument is a variable name (typically created via typeset -b); its value is retrieved and printed.

%d

An additional period and the output base can follow the precision (e.g., %5.3.6d to produce output in base 6).

%H

Output strings in HTML/XML format. (Spaces become &nbsp; and < and > become &lt; and &gt;.)

%n

Place the number of characters printed so far into the named variable.

%P

Translate egrep extended regular expression into ksh pattern.

%q

Print a quoted string that can be reread later on.

%R

Reverse of %P: translate ksh pattern into egrep extended regular expression.

%(format)T

Print a string representing a date and time according to the strftime(3) format format. The parentheses are entered literally. See the Examples.

%Z

Print an ASCII NUL (8 zero bits).

Examples

    $ date               Reformat date/time
    Tue Sep  7 15:39:42 EDT 2004
    $ printf "%(It is now %m/%d/%Y %H:%M:%S)T\n" "$(date)"
    It is now 09/07/2004 15:40:10

    $ printf "%H\n" "Here is a <string>"      Convert to HTML
    Here&nbsp;is&nbsp;a&nbsp;&lt;string&gt;

pushd
    pushd [-n] [directory]
    pushd [-n] [+count] [-count]

Bash only. Add directory to the directory stack, or rotate the directory stack. With no arguments, swap the top two entries on the stack, and change to the new top entry.

Options

-n

Don't change to the new top directory, just manipulate the stack.

+count

Rotate the stack so that the count'th item from the left, as shown by dirs, is the new top of the stack. Counting starts at zero. The new top becomes the current directory.

-count

Rotate the stack so that the count'th item from the left, as shown by dirs, is the new top of the stack. Counting starts at zero. The new top becomes the current directory.

pwd
    pwd [-LP]

Print your present working directory on standard output.

Options

Options give control over the use of logical versus physical treatment of the printed path. See also the entry for cd, earlier in this section.

-L

Use logical path (what the user typed, including any symbolic links) and the value of PWD for the current directory. This is the default.

-P

Use the actual filesystem physical path for the current directory.

r
    r

ksh88 alias for fc -e -. ksh93 alias for hist -s. Reexecute previous command.

read
    read [options] [variable1[?string]] [variable2 ...]

Read one line of standard input and assign each word to the corresponding variable, with all leftover words assigned to the last variable. If only one variable is specified, the entire line is assigned to that variable. See the Examples here and under case. The return status is 0 unless EOF is reached. Both Bash and the Korn shell support options, as shown below. If no variables are given, input is stored in the REPLY variable.

Additionally, the Korn shell version supports the ? syntax for prompting. If the first variable is followed by ?string, string is displayed as a user prompt.

Options

-a array

Read into indexed array array. Bash only.

-A array

Read into indexed array array. ksh93 only.

-d delim

Read up to first occurrence of delim, instead of newline. Not ksh88.

-e

Use the readline library if reading from a terminal. Bash only.

-n count

Read at most count bytes. Not ksh88.

-p prompt

Bash: print prompt before reading input.

-p

Korn shell: read from the output of a |& coprocess.

-r

Raw mode; ignore \ as a line-continuation character.

-s

Bash: read silently; characters are not echoed.

-s

Korn shell: save input as a command in the history file.

-t timeout

When reading from a terminal or pipe, if no data is entered after timeout seconds, return 1. This prevents an application from hanging forever, waiting for user input. Not ksh88.

-u[n]

Read input from file descriptor n (default is 0).

Examples

Read three variables:

    $ read first last address
    Sarah Caldwell 123 Main Street

    $ echo "$last, $first\n$address"
    Caldwell, Sarah
    123 Main Street

Prompt yourself to enter two temperatures, Korn shell version:

    $ read n1?"High low: " n2
    High low: 65 33

readonly
    readonly [-afp] [variable[=value] ...]

Prevent the specified shell variables from being assigned new values. An initial value may be supplied using the assignment syntax, but that value may not be changed subsequently.

Options

ksh88 does not accept options for this command.

-a

Each variable must refer to an array. Bash only.

-f

Each variable must refer to an function. Bash only.

-p

Print readonly before printing the names and values of read-only variables. This allows saving a list of read-only variables for rereading later.

redirect
    redirect i/o-redirection ...

ksh93 alias for command exec.

Example

Change the shell's standard error to the console:

    $ redirect 2>/dev/console

return
    return [n]

Use inside a function definition. Exit the function with status n or with the exit status of the previously executed command.

select
    select x [in list]
    do
     commandsdone

Display a list of menu items on standard error, numbered in the order they are specified in list. If no in list is given, items are taken from the command line (via "$@"). Following the menu is a prompt string (set by PS3). At the PS3 prompt, users select a menu item by typing its line number, or they redisplay the menu by pressing the Enter key. User input is stored in the shell variable REPLY. If a valid item number is typed, commands are executed. Typing EOF terminates the loop.

Example

    PS3="Select the item number: "
    select event in Format Page View Exit
    do
       case "$event" in
         Format) nroff $file | lp;;
         Page)   pr $file | lp;;
         View)   more $file;;
         Exit)   exit 0;;
         *   )   echo "Invalid selection";;
       esac
    done

The output of this script looks like this:

    1. Format
    2. Page
    3. View
    4. Exit
    Select the item number:

set
    set [options arg1 arg2 ...]

With no arguments, set prints the values of all variables known to the current shell. Options can be enabled (-option) or disabled (+option). Options can also be set when the shell is invoked. (See the earlier section Invoking the Shell.") Arguments are assigned in order to $1, $2, etc.

Options

There is a large set of overlapping options among ksh88, ksh93 and Bash. To minimize confusion, the following list includes every option. The table provided after the list summarizes which options are available in which shells.

-a

From now on, automatically mark variables for export after defining or changing them.

+A name

Assign remaining arguments as elements of array name. Korn shell only.

-A name

Same as +A, but unset name before making assignments. Korn shell only.

-b

Print job completion messages as soon as jobs terminate; don't wait until the next prompt. Not ksh88.

-B

Enable brace expansion. On by default. Bash only.

-C

Prevent overwriting via > redirection; use >| to overwrite files. Not ksh88.

-e

Exit if a command yields a nonzero exit status. The ERR trap executes before the shell exits.

-E

Cause shell functions, command substitutions, and subshells to inherit the ERR trap. Bash only.

-f

Ignore filename metacharacters (e.g., * ? [ ]).

-G

Cause ** to also match subdirectories during filename expansion. ksh93 only.

-h

Locate commands as they are defined. The Korn shell creates tracked aliases, whereas Bash hashes command names. On by default. See hash.

-H

Enable csh-style history substitution. On by default. Bash only.

-k

Assignment of environment variables (var=value) takes effect regardless of where they appear on the command line. Normally, assignments must precede the command name.

-m

Enable job control; background jobs execute in a separate process group. -m is usually set automatically.

-n

Read commands but don't execute; useful for checking syntax. Both shells ignore this option if is interactive.

+o [mode]

With mode, disable the given shell option. Plain set +o prints the settings of all the current options. For Bash and ksh93, this is in a form that can be reread by the shell later.

-o [mode]

List shell modes, or turn on mode mode. Many modes can be set by other options. Modes are:

allexport

Same as -a.

bgnice

Run background jobs at lower priority. Korn shell only.

braceexpand

Same as -B. Bash only.

emacs

Set command-line editor to emacs.

errexit

Same as -e.

errtrace

Same as -E. Bash only.

functrace

Same as -T. Bash only.

globstar

Same as -G. ksh93 only.

gmacs

Set command-line editor to gmacs (like GNU Emacs). Korn shell only.

hashall

Same as -h. Bash only.

histexpand

Same as -H. Bash only.

history

Enable command history. On by default. Bash only.

ignoreeof

Don't process EOF signals. To exit the shell, type exit.

keyword

Same as -k.

markdirs

Append / to directory names. Korn shell only.

monitor

Same as -m.

noclobber

Same as -C.

noexec

Same as -n.

noglob

Same as -f.

nolog

Omit function definitions from history file. Accepted but ignored by Bash.

notify

Same as -b.

nounset

Same as -u.

onecmd

Same as -t. Bash only.

physical

Same as -P. Bash only.

pipefail

Change pipeline exit status to be that of the rightmost command that failed, or zero if all exited successfully. Not ksh88.

posix

Change to POSIX mode. Bash only.

privileged

Same as -p.

trackall

Same as -h. Korn shell only.

verbose

Same as -v.

vi

Set command-line editor to vi.

viraw

Same as vi, but process each character when it's typed. Korn shell only.

xtrace

Same as -x.

+p

Reset effective UID to real UID.

-p

Start up as a privileged user. Bash: Don't read $ENV or $BASH_ENV, don't import functions from the environment, and ignore the value of $SHELLOPTS. Korn shell: Don't process $HOME/.profile, read /etc/suid_profile instead of $ENV.

-P

Always use physical paths for cd and pwd. Bash only.

-s

Sort the positional parameters. Korn shell only.

-t

Exit after one command is executed.

-T

Cause shell functions, command substitutions, and subshells to inherit the DEBUG trap. Bash only.

-u

In substitutions, treat unset variables as errors.

-v

Show each shell command line when read.

-x

Show commands and arguments when executed, preceded by the value of PS4. This provides step-by-step tracing of shell scripts.

-

Turn off -v and -x, and turn off option processing. Included for compatibility with older versions of the Bourne shell.

--

Used as the last option; -- turns off option processing so that arguments beginning with - are not misinterpreted as options. (For example, you can set $1 to -1.) If no arguments are given after --, unset the positional parameters.

Option Availability Summary

Option | Same as | ksh88 | ksh93 | Bash
-a | -o allexport | · | · | ·
-A |  | · | · |
-b | -o notify |  | · | ·
-B | -o braceexpand |  |  | ·
-C | -o noclobber |  | · | ·
-e | -o errexit | · | · | ·
-E | -o errtrace |  |  | ·
-f | -o noglob | · | · | ·
-G | -o globstar |  | · |
-h | -o hashall |  |  | ·
-h | -o trackall | · | · |
-H | -o histexpand |  |  | ·
-k | -o keyword | · | · | ·
-m | -o monitor | · | · | ·
-n | -o noexec | · | · | ·
-o allexport | -a | · | · | ·
-o bgnice |  | · | · |
-o braceexpand | -B |  |  | ·
-o emacs |  | · | · | ·
-o errexit | -e | · | · | ·
-o errtrace | -E |  |  | ·
-o functrace | -T |  |  | ·
-o globstar | -G |  | · |
-o gmacs |  | · | · |
-o hashall | -h |  |  | ·
-o history |  |  |  | ·
-o histexpand | -H |  |  | ·
-o ignoreeof |  | · | · | ·
-o keyword | -k | · | · | ·
-o markdirs |  | · | · |
-o monitor | -m | · | · | ·
-o noclobber | -C | · | · | ·
-o noexec | -n | · | · | ·
-o noglob | -f | · | · | ·
-o nolog |  | · | · |
-o notify | -b |  | · | ·
-o nounset | -u |  |  | ·
-o onecmd | -t |  |  | ·
-o physical | -P |  |  | ·
-o pipefail |  |  | · | ·
-o posix |  |  |  | ·
-o privileged | -p | · | · | ·
-o trackall | -h | · | · |
-o verbose | -v | · | · | ·
-o vi |  | · | · | ·
-o viraw |  | · | · |
-o xtrace | -x | · | · | ·
-p | -o privileged | · | · | ·
-P | -o physical |  |  | ·
-s |  | · | · |
-t | -o onecmd | · | · | ·
-T | -o functrace |  |  | ·
-u | -o nonunset | · | · | ·
-v | -o verbose | · | · | ·
-x | -o xtrace | · | · | ·

Examples

    set -- "$num" -20 -30   Set $1 to $num, $2 to -20, $3 to -30
    set -vx                 Read each command line; show it;
                            execute it; show it again (with arguments)
    set +x                  Stop command tracing
    set -o noclobber        Prevent file overwriting
    set +o noclobber        Allow file overwriting again

shopt
    shopt [-opqsu] [option]

Bash only. Sets or unsets shell options. With no options or just -p, prints the names and settings of the options.

Options

-o

Each option must be one of the shell option names for set -o, instead of the options listed in the next section.

-p

Print the option settings as shopt commands that can be reread later.

-q

Quiet mode. The exit status is zero if the given option is set, nonzero otherwise. With multiple options, all of them must be set for a zero exit status.

-s

Set the given options. With no options, prints only those that are set.

-u

Unset the given options. With no options, prints only those that are unset.

Settable Shell Options

The following descriptions describe the behavior when set. Options marked with a dagger (|) are enabled by default.

cdable_vars

Treat a nondirectory argument to cd as a variable whose value is the directory to go to.

cdspell

Attempt spelling correction on each directory component of an argument to cd. Allowed in interactive shells only.

checkhash

Check that commands found in the hash table still exist before attempting to use them. If not, perform a normal PATH search.

checkwinsize

Check the window size after each command and update LINES and COLUMNS if the size has changed.

cmdhist |

Save all lines of a multiline command in one history entry. This permits easy re-editing of multiline commands.

dotglob

Include filenames starting with a period in the results of filename expansion.

execfail

Do not exit a noninteractive shell if the command given to exec cannot be executed. Interactive shells do not exit in such a case, no matter the setting of this option.

expand_aliases |

Expand aliases created with alias. Disabled in noninteractive shells.

extdebug

Enable behavior needed for debuggers:

  • declare -F displays the source file name and line number for each function name argument.

  • When a command run by the DEBUG trap fails, the next command is skipped.

  • When a command run by the DEBUG trap inside a shell function or script sourced with . (dot) or source returns with an exit status of 2, the shell simulates a call to return.

  • BASH_ARGC and BASH_ARGV are set as described earlier.

  • Function tracing is enabled. Command substitutions, shell functions, and subshells invoked via (...) inherit the DEBUG and RETURN traps.

  • Error tracing is enabled. Command substitutions, shell functions, and subshells invoked via (...) inherit the ERROR trap.

extglob

Enable extended pattern-matching facilities such as +(...). (These were not in the Bourne shell and are not in POSIX; thus Bash requires you to enable them if you want them.)

extquote |

Allow $'...' and $"..." within ${variable} expansions inside double quotes.

failglob

Cause patterns that do not match filenames to produce an error.

force_fignore |

When doing completion, ignore words matching the list of suffixes in FIGNORE, even if such words are the only possible completions.

gnu_errfmt

Print error messages in the standard GNU format.

histappend

Append the history list to the file named by HISTFILE upon exit, instead of overwriting the file.

histreedit

Allow a user to re-edit a failed csh-style history substitution with the readline library.

histverify

Place the results of csh-style history substitution into the readline library's editing buffer, in case the user wishes to modify it further, instead of executing it directly.

hostcomplete |

If using readline, attempt hostname completion when a word containing an @ is being completed.

huponexit

Send a SIGHUP to all running jobs upon exiting an interactive shell.

interactive_comments |

Allow words beginning with # to start a comment in an interactive shell.

lithist

If cmdhist is also set, save mutliline commands to the history file with newlines instead of semicolons.

login_shell

Set by the shell when it is a login shell. This is a read-only option.

mailwarn

Print the message "The mail in mailfile has been read" when a file being checked for mail has been accessed since the last time Bash checked it.

no_empty_cmd_completion

If using readline, do not search $PATH when a completion is attempted on an empty line.

nocaseglob

Ignore letter case when doing filename matching.

nullglob

Expand patterns that do not match any files to the null string, instead of using the literal pattern as an argument.

progcomp |

Enable programmable completion.

promptvars |

Perform variable, command, and arithmetic substitution on the values of PS1, PS2 and PS4.

restricted_shell

Set by the shell when it is a restricted shell. This is a read-only option.

shift_verbose

Causes shift to print an error message when the shift count is greater than the number of positional parameters.

sourcepath |

Causes the . (dot) and source commands to search $PATH in order to find the file to read and execute.

xpg_echo

Causes echo to expand escape sequences, even without the -e or -E options.

shift
    shift [n]

Shift positional arguments (e.g., $2 becomes $1). If n is given, shift to the left n places. Used in while loops to iterate through command-line arguments. In the Korn shell, n can be an integer expression.

Examples

    shift $1+$6          Korn shell: use expression result as shift count
    shift $(($1 + $6))   Same, portable to any POSIX shell

sleep
    sleep [n]

ksh93 only. Sleep for n seconds. n can have a fractional part.

source
    source file [arguments]

Bash only. Identical to the . (dot) command; see that entry.

stop
    stop [jobIDs]

ksh88 alias for kill -STOP. ksh93 alias for kill -s STOP. Suspend the background job specified by jobIDs; this is the complement of Ctrl-Z or suspend. See the earlier section Job Control."

suspend
    suspend [-f]

Suspend the current shell. Often used to stop an su command. In ksh88, suspend is an alias for kill -STOP $$. In ksh93, it is an alias for kill -s STOP $$. In Bash, it is a built-in command.

Options

-f

Force the suspension, even if the shell is a login shell. Bash only.

test
    test condition or
    [ condition ]
     or
    [[ condition ]]

Evaluate a condition and, if its value is true, return a zero exit status; otherwise, return a nonzero exit status. An alternate form of the command uses [] rather than the word test. An additional alternate form uses [[]], in which case word splitting and pathname expansion are not done. (See the [[ ]] entry.) condition is constructed using the following expressions. Conditions are true if the description holds true. Features that are specific to Bash are marked with a (B). Features that are specific to the Korn shell are marked with a (K). Features that are specific to ksh93 are marked with a (K93).

File Conditions

-a file

file exists.

-b file

file exists and is a block special file.

-c file

file exists and is a character special file.

-C file

file exists and is a contiguous file. This facility is not available on most Unix systems. (K)

-d file

file exists and is a directory.

-f file

file exists and is a regular file.

-g file

file exists, and its set-group-id bit is set.

-G file

file exists, and its group is the effective group ID.

-h file

file exists and is a symbolic link.

-k file

file exists, and its sticky bit is set.

-L file

file exists and is a symbolic link.

-N file

file exists and was modified after it was last read. (B)

-O file

file exists, and its owner is the effective user ID.

-p file

file exists and is a named pipe (fifo).

-r file

file exists and is readable.

-s file

file exists and has a size greater than zero.

-S file

file exists and is a socket.

-t [n]

The open file descriptor n is associated with a terminal device; default n is 1.

-u file

file exists, and its set-user-id bit is set.

-w file

file exists and is writable.

-x file

file exists and is executable.

f1 -ef f2

Files f1 and f2 are linked (refer to same file).

f1 -nt f2

File f1 is newer than f2.

f1 -ot f2

File f1 is older than f2.

String conditions

string

string is not null.

-n s1

String s1 has nonzero length.

-z s1

String s1 has zero length.

s1 = s2

Strings s1 and s2 are identical. s2 can be a wildcard pattern. Quote s2 to treat it literally. (See the Filename Metacharacters section, earlier in this chapter.) (K)

s1 = = s2

Strings s1 and s2 are identical. s2 can be a wildcard pattern. Quote s2 to treat it literally. Preferred over =. (B, K93)

s1 != s2

Strings s1 and s2 are not identical. s2 can be a wildcard pattern. Quote s2 to treat it literally.

s1 =~ s2

String s1 matches extended regular expression s2. Quote s2 to keep the shell from expanding embedded shell metacharacters. Strings matched by parenthesized subexpressions are placed into elements of the BASH_REMATCH array. See the description of BASH_REMATCH earlier in this chapter. (B)

s1 < s2

ASCII value of s1 precedes that of s2. (Valid only within [[ ]] construct.)

s1 > s2

ASCII value of s1 follows that of s2. (Valid only within [[ ]] construct.)

Internal shell conditions

-o opt

Option opt for set -o is on.

Integer comparisons

n1 -eq n2

n1 equals n2.

n1 -ge n2

n1 is greater than or equal to n2.

n1 -gt n2

n1 is greater than n2.

n1 -le n2

n1 is less than or equal to n2.

n1 -lt n2

n1 is less than n2.

n1 -ne n2

n1 does not equal n2.

Combined forms

(condition)

True if condition is true (used for grouping). For test and [ ], the ( )s should be quoted by a \. The form using [[ ]] doesn't require quoting the parentheses.

! condition

True if condition is false.

condition1 -a condition2

True if both conditions are true.

condition1 && condition2

True if both conditions are true. (Valid only within [[ ]] construct.)

condition1 -o condition2

True if either condition is true.

condition1 || condition2

True if either condition is true. (Valid only within [[ ]] construct.)

Examples

The following examples show the first line of various statements that might use a test condition:

    while test $# -gt 0             While there are arguments...
    while [ -n "$1" ]         While there are nonempty arguments...
    if [ $count -lt 10 ]     If $count is less than 10...
    if [ -d RCS ]                   If the RCS directory exists...
    if [ "$answer" != "y" ]         If the answer is not y...
    if [ ! -r "$1" -o ! -f "$1" ]   If the first argument is not a
                                    readable file or a regular file...

time
    time commandtime [command]

Execute command and print the total elapsed time, user time, and system time (in seconds). Same as the Unix command time (see Chapter 3), except that the built-in version can also time other built-in commands as well as all commands in a pipeline.

The second form applies to ksh93; with no command, the total user and system times for the shell and all children are printed.

times
    times

Print accumulated process times for user and system.

times
    times

ksh93 alias for { {time;} 2>&1;}. See also time.

trap
    trap [ [commands] signals]
    trap -p
    trap -l

Execute commands if any signals are received. The second form is specific to Bash and ksh93; it prints the current trap settings in a form suitable for rereading later. The third form is specific to Bash; it lists all signals and their numbers, like kill -l.

Common signals include EXIT (0), HUP (1), INT (2), and TERM (15). Multiple commands must be quoted as a group and separated by semicolons internally. If commands is the null string (i.e., trap "" signals), signals are ignored by the shell. If commands are omitted entirely, reset processing of specified signals to the default action. Bash and ksh93: if commands is "-", reset signals to their initial defaults.

If both commands and signals are omitted, list current trap assignments. See the Examples here and in exec.

Signals

A list of signal names, numbers, and meanings were given earlier in the kill entry; see the listing there. The shells allow you to use either the signal number or the signal name (without the SIG prefix). In addition, the shells support "pseudo-signals," signal names or numbers that aren't real operating system signals but which direct the shell to perform a specific action. These signals are:

DEBUG

Execution of any command.

ERR

Nonzero exit status.

EXIT

Exit from shell (usually when shell script finishes).

0

Same as EXIT, for historical compatibility with the Bourne shell.

KEYBD

A key has been read in emacs, gmacs, or vi editing mode. ksh93 only.

RETURN

A return is executed, or a script run with . (dot) or source finishes. Bash only.

Examples

    trap "" INT       Ignore interrupts (signal 2)
    trap INT          Obey interrupts again

Remove a $tmp file when the shell program exits, or if the user logs out, presses Ctrl-C, or does a kill:

    trap "rm -f $tmp; exit" EXIT HUP INT TERM       POSIX style
    trap "rm -f $tmp; exit" 0 1 2 15    Pre-POSIX Bourne shell style

Print a "clean up" message when the shell program receives signals SIGHUP, SIGINT, or SIGTERM:

    trap 'echo Interrupt!  Cleaning up...' HUP INT TERM

true
    true

ksh88 alias for :. Bash and ksh93 built-in command that exits with a true return value.

type
    type [-afpPt] commands

Bash version. Show whether each command name is a Unix command, a built-in command, an alias, a shell keyword, or a defined shell function.

Options

-a

Print all locations in $PATH that include command, including aliases and functions. Use -p together with -a to suppress aliases and functions.

-f

Suppress function lookup, as with command.

-p

If type -t would print file for a given command, this option prints the full pathname for the executable files. Otherwise, it prints nothing.

-P

Like -p, but force a PATH search, even if type -t would not print file.

-t

Print a word describing each command. The word is one of alias, builtin, file, function, or keyword, depending upon the type of each command.

Example

    $ type mv read if
    mv is /bin/mv
    read is a shell builtin
    if is a shell keyword

type
    type commands

Korn shell alias for whence -v.

typeset
    typeset [options] [variable[=value ...]]
    typeset -p

In Bash, identical to declare. See declare.

In the Korn shell, assign a type to each variable (along with an optional initial value), or, if no variables are supplied, display all variables of a particular type (as determined by the options). When variables are specified, -option enables the type, and +option disables it. With no variables, -option prints variable names and values; +option prints only the names.

The second form shown is specific to ksh93.

Options

-A arr

arr is an associative array. ksh93 only.

-b

The variable can hold any data, including binary data. References retrieve the value printed in base-64 notation; The %B format with printf may be used to print the value. ksh93 only.

-E d

variable is a floating-point number. d is the number of decimal places. The value is printed using printf %g format. ksh93 only.

-f[c]

The named variable is a function; no assignment is allowed. If no variable is given, list current function names. Flag c can be t, u, or x. t turns on tracing (same as set -x). u marks the function as undefined, which causes autoloading of the function (i.e., a search of FPATH locates the function when it's first used. ksh93 also searches PATH). In ksh88, x exports the function. In ksh93, x is accepted but does nothing. Note the aliases autoload and functions.

-F d

variable is a floating-point number. d is the number of decimal places. The value is printed using printf %f format. ksh93 only.

-H

On non-Unix systems, map Unix filenames to host filenames.

-i[n]

Define variables as integers of base n. integer is an alias for typeset -i.

-L[n]

Define variables as left-justified strings, n characters long (truncate or pad with blanks on the right as needed). Leading blanks are stripped; leading zeroes are stripped if -Z is also specified. If no n is supplied, field width is that of the variable's first assigned value.

-l

Convert uppercase to lowercase.

-n

variable is an indirect reference to another variable (a nameref ). ksh93 only. (See the Variables," section, earlier in this chapter.)

-p

Print typeset commands to re-create the types of all the current variables. ksh93 only.

-R[n]

Define variables as right-justified strings, n characters long (truncate or pad with blanks on the left as needed). Trailing blanks are stripped. If no n is supplied, field width is that of the variable's first assigned value.

-r

Mark variables as read-only. See also readonly.

-t

Mark variables with a user-definable tag.

-u

Convert lowercase to uppercase.

-ui[n]

Define variables as unsigned integers of base n. ksh93 only.

-x

Mark variables for automatic export.

-Z[n]

When used with -L, strip leading zeroes. When used alone, it's similar to -R, except that -Z pads numeric values with zeroes and pads text values with blanks.

Examples

    typeset                 List name, value, and type of all set variables
    typeset -x              List names and values of exported variables
    typeset +r PWD          End read-only status of PWD
    typeset -i n1 n2 n3     Three variables are integers
    typeset -R5 zipcode     zipcode is flush right, five characters wide

ulimit
    ulimit [options] [n]

Print the value of one or more resource limits, or, if n is specified, set a resource limit to n. Resource limits can be either hard (-H) or soft (-S). By default, ulimit sets both limits or prints the soft limit. The options determine which resource is acted on.

Options

-H

Hard limit. Anyone can lower a hard limit; only privileged users can raise it.

-S

Soft limit. Must be lower than the hard limit.

-a

Print all limits.

-b

Size of socket buffers. ksh93 only.

-c

Maximum size of core files.

-d

Maximum kilobytes of data segment or heap.

-f

Maximum size of files (the default option).

-l

Maximum size of address space that can be locked in memory. Not ksh88.

-L

Maximum number of file locks. ksh93 only.

-m

Maximum kilobytes of physical memory. (Not effective on all Unix systems.)

-M

Maximum size of the address space. ksh93 only.

-n

Maximum number of file descriptors.

-p

Size of pipe buffers. (Not effective on all Unix systems.)

-s

Maximum kilobytes of stack segment.

-t

Maximum CPU seconds.

-T

Maximum number of threads. ksh93 only.

-u

Maximum number of processes a single user can have.

-v

Maximum kilobytes of virtual memory.

umask
    umask [nnn]
    umask [-pS] [mask]

Display file creation mask or set file creation mask to octal value nnn. The file creation mask determines which permission bits are turned off (e.g., umask 002 produces rw-rw-r--). See the entry in Chapter 3 for examples.

The second form is not in ksh88. A symbolic mask is permissions to keep.

Option

-p

Output is in a form that can be reread later by the shell. Bash only.

-S

Print the current mask using symbolic notation. Not ksh88.

unalias
    unalias namesunalias -a

Remove names from the alias list. See also alias.

Option

-a

Remove all aliases. Not ksh88.

unset
    unset [options] names

Erase definitions of functions or variables listed in names.

Options

-f

Unset functions names.

-n

Unset indirect variable (nameref) name, not the variable the nameref refers to. ksh93 only.

-v

Unset variables names (default). Not ksh88.

until
    until conditiondo
     commandsdone

Until condition is met, do commands. condition is often specified with the test command. See the Examples under case and test.

wait
    wait [ID]

Pause in execution until all background jobs complete (exit status 0 is returned), or pause until the specified background process ID or job ID completes (exit status of ID is returned). Note that the shell variable $! contains the process ID of the most recent background process.

Example

    wait $!   Wait for most recent background process to finish

whence
    whence [options] commands

Korn shell only. Show whether each command name is a Unix command, a built-in command, a defined shell function, or an alias.

Options

-a

Print all interpretations of commands. ksh93 only.

-f

Skip the search for shell functions. ksh93 only.

-p

Search for the pathname of commands.

-v

Verbose output.

while
    while conditiondo
     commands
    done

While condition is met, do commands. condition is often specified with the test command. See the Examples under case and test.


Chapter 7. Pattern Matching

A number of Linux text-processing utilities let you search for, and in some cases change, text patterns rather than fixed strings. These utilities include the editing programs ed, ex, vi, and sed; the gawk programming language; and the commands grep and egrep. Text patterns (called regular expressions in computer science literature) contain normal characters mixed with special characters (called metacharacters).

This chapter presents the following topics:

  • Filenames versus patterns

  • Description of metacharacters

  • List of metacharacters available to each program

  • Examples

For more information on regular expressions, see the O'Reilly book Mastering Regular Expressions.


Section 7.1. Filenames Versus Patterns

7.1. Filenames Versus Patterns

Metacharacters used in pattern matching are different from metacharacters used for filename expansion (see Chapter 6). However, several metacharacters have meaning for both regular expressions and for filename expansion. This can lead to a problem: the shell sees the command line first, and can potentially interpret an unquoted regular expression metacharacter as a filename expansion. For example, the command:

    $ grep [A-Z]* chap[12]

could be transformed by the shell into:

    $ grep Array.c Bug.c Comp.c chap1 chap2

and grep would then try to find the pattern Array.c in files Bug.c, Comp.c, chap1, and chap2. To bypass the shell and pass the special characters to grep, use quotes as follows:

    $ grep "[A-Z]*" chap[12]

Double quotes suffice in most cases, but single quotes are the safest bet, since the shell does absolutely no expansions on single-quoted text.

Note also that in pattern matching, ? matches zero or one instance of a regular expression; in filename expansion, ? matches a single character.


Section 7.2. Metacharacters

7.2. Metacharacters

Different metacharacters have different meanings, depending upon where they are used. In particular, regular expressions used for searching through text (matching) have one set of metacharacters, while the metacharacters used when processing replacement text (such as in a text editor) have a different set. These sets also vary somewhat per program. This section covers the metacharacters used for searching and replacing, with descriptions of the variants in the different utilities.

7.2.1. Search Patterns

The characters in the following table have special meaning only in search patterns.

Character | Pattern
. | Match any single character except newline. Can match newline in awk.
* | Match any number (or none) of the single character that immediately precedes it. The preceding character can also be a regular expression. For example, since . (dot) means any character, .* means "match any number of any character."
^ | Match the following regular expression at the beginning of the line or string.
$ | Match the preceding regular expression at the end of the line or string.
[ ] | Match any one of the enclosed characters.
 | A hyphen (-) indicates a range of consecutive characters. A circumflex (^) as the first character in the brackets reverses the sense: it matches any one character not in the list. A hyphen or close bracket (]) as the first character is treated as a member of the list. All other metacharacters are treated as members of the list (i.e., literally).
{n,m} | Match a range of occurrences of the single character that immediately precedes it. The preceding character can also be a regular expression. {n} matches exactly n occurrences, {n,} matches at least n occurrences, and {n,m} matches any number of occurrences between n and m. n and m must be between 0 and 255, inclusive. (The GNU programs on Linux allow a range of 0 to 32767.)
\{n,m\} | Just like {n,m}, earlier, but with backslashes in front of the braces. (Historically, different utilities used different syntaxes for the same thing.)
\ | Turn off the special meaning of the following character.
\( \) | Save the subpattern enclosed between \( and \) into a special holding space. Up to nine subpatterns can be saved on a single line. The text matched by the subpatterns can be "replayed" in substitutions by the escape sequences \1 to \9.
\n | Replay the nth subpattern enclosed in \( and \) into the pattern at this point. n is a number from 1 to 9, with 1 starting on the left. See the following Examples.
\< \> | Match characters at beginning (\<) or end (\>) of a word.
+ | Match one or more instances of preceding regular expression.
? | Match zero or one instances of preceding regular expression.
| | Match the regular expression specified before or after the vertical bar (alternation).
( ) | Apply a match to the enclosed group of regular expressions.

Linux allows the use of POSIX "character classes" within the square brackets that enclose a group of characters. They are typed enclosed in [: and :]. For example, [[:alnum:]] matches a single alphanumeric character.

Class | Characters matched | Class | Characters matched
alnum | Alphanumeric characters | lower | Lowercase characters
alpha | Alphabetic characters | print | Printable characters
blank | Space or Tab | punct | Punctuation characters
cntrl | Control characters | space | Whitespace characters
digit | Decimal digits | upper | Uppercase characters
graph | Non-space characters | xdigit | Hexadecimal digits

Finally, the GNU utilities on Linux accept additional escape sequences that act like metacharacters. (Because \b can also be interpreted as the sequence for the ASCII Backspace character, different utilities treat it differently. Check each utility's documentation.)

Sequence | Meaning
\b | Word boundary, either beginning or end of a word, as for the \< and \> metacharacters described earlier.
\B | Interword match; matches between two word-constituent characters.
\w | Matches any word-constituent character; equivalent to [[:alnum:]_].
\W | Matches any non-word-constituent character; equivalent to [^[:alnum:]_].
\` | Beginning of an Emacs buffer. Used by most other GNU utilities to mean unambiguously "beginning of string."
\' | End of an Emacs buffer. Used by most other GNU utilities to mean unambiguously "end of string."

7.2.2. Replacement Patterns

The characters in the following table have special meaning only in replacement patterns.

Character | Pattern
\ | Turn off the special meaning of the following character.
\n | Reuse the text matched by the nth subpattern previously saved by \( and \) as part of the replacement pattern. n is a number from 1 to 9, with 1 starting on the left.
& | Reuse the text matched by the search pattern as part of the replacement pattern.
~ | Reuse the previous replacement pattern in the current replacement pattern. Must be the only character in the replacement pattern (ex and vi).
% | Reuse the previous replacement pattern in the current replacement pattern. Must be the only character in the replacement pattern (ed).
\u | Convert first character of replacement pattern to uppercase.
\U | Convert entire replacement pattern to uppercase.
\l | Convert first character of replacement pattern to lowercase.
\L | Convert entire replacement pattern to lowercase.
\e | Turn off previous \u or \l.
\E | Turn off previous \U or \L.


Section 7.3. Metacharacters, Listed by Program

7.3. Metacharacters, Listed by Program

Some metacharacters are valid for one program but not for another. Those that are available are marked by a bullet (•) in the following table. Items marked with a "P" are specified by POSIX. Full descriptions were provided in the previous section.

Symbol | ed | ex | vi | sed | awk | grep | egrep | Action
. | • | • | • | • | • | • | • | Match any character.
* | • | • | • | • | • | • | • | Match zero or more preceding characters.
^ | • | • | • | • | • | • | • | Match beginning of line/string.
$ | • | • | • | • | • | • | • | Match end of line/string.
\ | • | • | • | • | • | • | • | Escape following character.
[ ] | • | • | • | • | • | • | • | Match one from a set.
\( \) | • | • | • | • |  | • |  | Store pattern for later replay.[a]
\n | • | • | • | • |  | • |  | Replay subpattern in match.
{ } |  |  |  |  | • P |  | • P | Match a range of instances.
\{ \} | • |  |  | • |  | • |  | Match a range of instances.
\< \> | • | • | • |  |  |  |  | Match word's beginning or end.
+ |  |  |  |  | • |  | • | Match one or more preceding characters.
? |  |  |  |  | • |  | • | Match zero or one preceding characters.
| |  |  |  |  | • |  | • | Separate choices to match.
( ) |  |  |  |  | • |  | • | Group expressions to match.

[a] Stored subpatterns can be "replayed" during matching. See the following table.

Note that in ed, ex, vi, and sed, you specify both a search pattern (on the left) and a replacement pattern (on the right). The metacharacters listed above are meaningful only in a search pattern.

In ed, ex, vi, and sed, the metacharacters in the following table are valid only in a replacement pattern.

Symbol | ex | vi | sed | ed | Action
\ | • | • | • | • | Escape following character.
\n | • | • | • | • | Text matching pattern stored in \( \).
& | • | • | • | • | Text matching search pattern.
~ | • | • |  |  | Reuse previous replacement pattern.
% |  |  |  | • | Reuse previous replacement pattern.
\u \U | • | • |  |  | Change character(s) to uppercase.
\l \L | • | • |  |  | Change character(s) to lowercase.
\e | • | • |  |  | Turn off previous \u or \l.
\E | • | • |  |  | Turn off previous \U or \L.


Section 7.4. Examples of Searching

7.4. Examples of Searching

When used with grep or egrep, regular expressions should be surrounded by quotes. (If the pattern contains a $, you must use single quotes; e.g., 'pattern'.) When used with ed, ex, sed, and awk, regular expressions are usually surrounded by /, although (except for awk) any delimiter works. The following tables show some sample patterns.

Pattern | What does it match?
bag | The string bag.
^bag | bag at the beginning of the line.
bag$ | bag at the end of the line.
^bag$ | bag as the only word on the line.
[Bb]ag | Bag or bag.
b[aeiou]g | Second letter is a vowel.
b[^aeiou]g | Second letter is a consonant (or uppercase or symbol).
b.g | Second letter is any character.
^...$ | Any line containing exactly three characters.
^\. | Any line that begins with a dot.
^\.[a-z][a-z] | Same, followed by two lowercase letters (e.g., troff requests).
^\.[a-z]\{2\} | Same as previous; ed, grep, and sed only.
^[^.] | Any line that doesn't begin with a dot.
bugs* | bug, bugs, bugss, etc.
"word" | A word in quotes.
"*word"* | A word, with or without quotes.
[A-Z][A-Z]* | One or more uppercase letters.
[A-Z]+ | Same; egrep or awk only.
[[:upper:]]+ | Same as previous, egrep or awk.
[A-Z].* | An uppercase letter, followed by zero or more characters.
[A-Z]* | Zero or more uppercase letters.
[a-zA-Z] | Any letter, either lower- or uppercase.
[^0-9A-Za-z] | Any symbol or space (not a letter or a number).
[^[:alnum:]] | Same, using POSIX character class.

egrep or awk pattern | What does it match?
[567] | One of the numbers 5, 6, or 7.
five|six|seven | One of the words five, six, or seven.
80[2-4]?86 | 8086, 80286, 80386, or 80486.
80[2-4]?86|(Pentium(-III?)?) | 8086, 80286, 80386, 80486, Pentium, Pentium-II, or Pentium-III.
compan(y|ies) | company or companies.

ex or vi pattern | What does it match?
\<the | Words like theater or the.
the\> | Words like breathe or the.
\<the\> | The word the.

ed, sed or grep pattern | What does it match?
0\{5,\} | Five or more zeros in a row.
[0-9]\{3\}-[0-9]\{2\}-[0-9]\{4\} | U.S. Social Security number (nnn-nn-nnnn).
\(why\).*\1 | A line with two occurrences of why.
\([[:alpha:]_][[:alnum:]_.]*\) = \1; | C/C++ simple assignment statements.

7.4.1. Examples of Searching and Replacing

The examples in the following table show the metacharacters available to sed or ex. Note that ex commands begin with a colon. A space is marked by a [image]; a tab is marked by a tab.

Command | Result
s/.*/( & )/ | Redo the entire line, but add spaces and parentheses.
s/.*/mv & &.old/ | Change a wordlist (one word per line) into mv commands.
/^$/d | Delete blank lines.
:g/^$/d | Same as previous, in ex editor.
/^[ [image] tab]*$/d | Delete blank lines, plus lines containing only spaces or tabs.
:g/^[ [image] tab]*$/d | Same as previous, in ex editor.
s/ [image] [image] */ [image] /g | Turn one or more spaces into one space.
:%s/ [image] [image] */ [image] /g | Same as previous, in ex editor.
:s/[0-9]/Item &:/ | Turn a number into an item label (on the current line).
:s | Repeat the substitution on the first occurrence.
:& | Same as previous.
:sg | Same as previous, but for all occurrences on the line.
:&g | Same as previous.
:%&g | Repeat the substitution globally (i.e., on all lines).
:.,$s/Fortran/\U&/g | On current line to last line, change word to uppercase.
:.,$s/\(F\)\(ORTRAN\)/\1\L\2/g | On current line to last line, change spelling of "FORTRAN" to correct, modern usage.
:%s/.*/\L&/ | Lowercase entire file.
:s/\<./\u&/g | Uppercase first letter of each word on current line. (Useful for titles.)
:%s/yes/No/g | Globally change a word to No.
:%s/Yes/~/g | Globally change a different word to No (previous replacement).

Finally, some sed examples for transposing words. A simple transposition of two words might look like this:

    s/die or do/do or die/     Transpose words

The real trick is to use hold buffers to transpose variable patterns. For example:

    s/\([Dd]ie\) or \([Dd]o\)/\2 or \1/  Transpose, using hold buffers


Chapter 8. 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, but this book documents the most popular one, GNU Emacs (Version 21.3), which is available from the Free Software Foundation (http://www.gnu.org/software/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.

This chapter presents the following topics:

  • Conceptual overview

  • Command-line syntax

  • Summary of emacs commands by group

  • Summary of emacs commands by key

  • Summary of emacs commands by name

For more information about Emacs, see the O'Reilly book Learning GNU Emacs.


Section 8.1. Conceptual Overview

8.1. Conceptual Overview

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

8.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 such as 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 such as 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 (O'Reilly) or the Emacs Info documentation system (C-h i).

8.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.

8.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.

8.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.

8.1.5. Notes on the Tables

Emacs commands use the Ctrl key and the Meta key (Meta is usually the Alt key or the Escape key). In this chapter, the notation C- indicates that the Ctrl key is pressed at the same time as the character that follows. Similarly, M- indicates the use of the Meta key. When using Escape for Meta, press and release the Escape key, then type the next key. If you use Alt (or Option on the Mac) for Meta, it is just like Ctrl or Shift, and you should press it simultaneously with the other key(s).

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. If there are no keystrokes for a given command, you'll see (none) in the first column. Access these commands by typing M-x followed by the command name. If you're unsure of the name, you can type a tab or a carriage return, and Emacs lists possible completions of what you've typed so far.

Because Emacs is such a comprehensive editor, containing literally thousands of commands, some commands must be omitted for the sake of preserving a "quick" reference. You can browse the command set by typing C-h (for help) or M-x Tab (for command names).

8.1.6. Absolutely Essential Commands

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

Keystrokes | Description
C-h | Enter the online help system.
C-x C-s | Save the file.
C-x C-c | Exit Emacs.
C-_ | Undo last edit (can be repeated).
C-g | Get out of current command operation.
C-p | Up/down/forward/back by line or character.
C-n |
C-f |
C-b |
C-v | Forward/backward by one screen.
M-v |
C-s | Search forward/backward for characters.
C-r |
C-d | Delete next/previous character.
Del |


Section 8.2. Command-Line Syntax

8.2. Command-Line Syntax

To start an Emacs editing session, type:

    emacs  [file ]


Section 8.3. Summary of Commands by Group

8.3. Summary of Commands by Group

Reminder: C- indicates the Ctrl key; M- indicates the Meta key.

8.3.1. File-Handling Commands

Keystrokes | Command name | Description
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 with C-x C-f.
C-x i | insert-file | Insert file at cursor position.
C-x C-s | save-buffer | Save file (may hang terminal; use C-q to restart).
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).

8.3.2. Cursor-Movement Commands

Keystrokes | Command name | Description
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.

8.3.3. Deletion Commands

Keystrokes | Command name | Description
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 next section).
(none) | backward-kill-paragraph | Delete previous paragraph.
(none) | kill-paragraph | Delete from the cursor to the end of the paragraph.

8.3.4. Paragraphs and Regions

Keystrokes | Command name | Description
C-@ | set-mark-command | Mark the beginning (or end) of a region.
C-Space | (same as above) | (same as above)
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.

8.3.5. Stopping and Undoing Commands

Keystrokes | Command name | Description
C-g | keyboard-quit | Abort current command.
C-_ | 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).

8.3.6. Transposition Commands

Keystrokes | Command name | Description
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.

8.3.7. Search Commands

Keystrokes | Command name | Description
C-s | isearch-forward | Incremental search forward.
C-r | isearch-backward | Incremental search backward
M-% | query-replace | Search and replace.
C-M-s Enter | re-search-forward | Regular expression search forward.
C-M-r Enter | re-search-backward | Regular expression search backward

8.3.8. Capitalization Commands

Keystrokes | Command name | Description
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 region.
C-x C-u | upcase-region | Uppercase region
C-x C-l | downcase-region | Lowercase region.

8.3.9. Word-Abbreviation Commands

Keystrokes | Command name | Description
(none) | abbrev-mode | Enter (or exit) word abbreviation mode.
C-x a i g | inverse-add-global-abbrev | Type global abbreviation, then definition.
C-x a i l | inverse-add-local-abbrev | Type local abbreviation, then definition.
(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.

8.3.10. Buffer-Manipulation Commands

Keystrokes | Command name | Description
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.

8.3.11. Window Commands

Keystrokes | Command name | Description
C-x 2 | split-window-vertically | Divide the current window into two, one on top of the other.
C-x 3 | split-window-horizontally | Divide the current window into two, side by side.
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.
C-M-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.

8.3.12. Special Shell Characters

Keystrokes | Command Name | Description
(none) | shell | Start a shell buffer.
C-c C-c | comint-interrupt-subjob | Terminate the current job.
C-c C-d | comint-send-eof | End of file character.
C-c C-u | comint-kill-input | Erase current line.
C-c C-w | backward-kill-word | Erase the previous word.
C-c C-z | comint-stop-subjob | Suspend the current job.

8.3.13. Indentation Commands

Keystrokes | Command name | Description
C-x . | set-fill-prefix | Use characters from the beginning of the line up to the cursor column as the "fill prefix." This prefix is prepended to each line in the paragraph. Cancel the 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.
C-M-\ | indent-region | Indent a region to match first line in region.
M-m | back-to-indentation | Move cursor to first character on line.
C-M-o | split-line | Split line at cursor; indent to column of cursor.
(none) | fill-individual-paragraphs | Reformat indented paragraphs, keeping indentation.

8.3.14. Centering Commands

Keystrokes | Command name | Description
M-s | center-line | Center line that cursor is on.
(none) | center-paragraph | Center paragraph that cursor is on.
(none) | center-region | Center currently defined region.

8.3.15. Macro Commands

Keystrokes | Command name | Description
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 ( | universal-argument and 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-keyboard-macro | Insert the macro you named into a file.
(none) | load-file | Load macro files you've saved and loaded.
(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.
C-M-c | exit-recursive-edit | Exit a recursive edit.

8.3.16. Basic Indentation Commands

Keystrokes | Command name | Description
C-M-\ | indent-region | Indent a region to match first line in region.
M-m | back-to-indentation | Move to first nonblank character on line.
M-^ | delete-indentation | Join this line to the previous one.

8.3.17. Detail Information Help Commands

Keystrokes | Command name | Description
C-h a | command-apropos | What commands involve this concept?
(none) | apropos | What 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?

8.3.18. Help Commands

Keystrokes | Command name | Description
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.


Section 8.4. Summary of Commands by Key

8.4. Summary of Commands by Key

Emacs commands are presented below in two alphabetical lists. Reminder: C- indicates the Ctrl key; M- indicates the Meta key.

8.4.1. Control-Key Sequences

Keystrokes | Command name | Description
C-@ | set-mark-command | Mark the beginning (or end) of a region.
C-Space | (same as previous) |
C-] | (none) | 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 | comint-interrupt-subjob | Terminate the current job.
C-c C-d | comint-send-eof | End-of-file character.
C-c C-u | comint-kill-input | Erase current line.
C-c C-w | backward-kill-word | Erase the previous word.
C-c C-z | comint-stop-subjob | Suspend the 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-c | describe-copying | View the Emacs General Public License.
C-h C-d | describe-distribution | View information on ordering Emacs from FSF.
C-h C-w | describe-no-warranty | View the (non-)warranty for Emacs.
C-h c | describe-key-briefly | What command does this keystroke sequence run?
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-M-\ | indent-region | Indent a region to match first line in region.
C-M-c | exit-recursive-edit | Exit a recursive edit.
C-M-o | split-line | Split line at cursor; indent to column of cursor.
C-M-v | scroll-other-window | Scroll other window.
C-n | next-line | Move to next line (down).
C-p | previous-line | Move to previous line (up).
C-r | isearch-backward | Start incremental search backward.
C-s | isearch-forward | Start incremental search forward.
C-t | transpose-chars | Transpose two letters.
C-u n | universal-argument | Repeat the next command n times.
C-u C-x ( | universal-argument and 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 | Use characters from the beginning of the line up to the cursor column as the "fill prefix." This prefix is prepended to each line in the paragraph. Cancel the 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 the current window into two, one on top of the other.
C-x 3 | split-window-horizontally | Divide the current window into two, side by side.
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 a new frame.
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 | Mark page.
C-x C-q | (none) | Toggle read-only status of buffer.
C-x C-s | save-buffer | Save file (may hang terminal; use C-q to restart).
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 read with C-x C-f.
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 a i g | inverse-add-global-abbrev | Type global abbreviation, then definition.
C-x a i l | inverse-add-local-abbrev | Type local abbreviation, then definition.
C-x b | switch-to-buffer | Move to the buffer specified.
C-x e | call-last-kbd-macro | Execute last macro defined.
C-x h | mark-whole-buffer | Mark 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-_ | advertised-undo | Undo last edit (can be done repeatedly).
C-y | yank | Restore what you've deleted.
C-z | suspend-emacs | Suspend Emacs (use exit or fg to restart).

8.4.2. Meta-Key Sequences

Keystrokes | Command name | Description
Meta | (none) | Exit a query-replace or successful search.
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-< | 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 and 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-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 | Mark paragraph.
M-k | kill-sentence | Delete sentence the 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-s | center-line | Center line that cursor is on.
M-t | transpose-words | Transpose two words.
M-u | upcase-word | Uppercase word.
M-v | scroll-down | Move backward one screen.
M-x | (none) | Access command by command name.


Section 8.5. Summary of Commands by Name

8.5. Summary of Commands by Name

The Emacs commands below are presented alphabetically by command name. Use M-x to access the command name. Reminder: C- indicates the Ctrl key; M- indicates the Meta key.

Command name | Keystrokes | Description
macroname | (none) | Execute a keyboard macro you've saved.
abbrev-mode | (none) | Enter (or exit) word abbreviation mode.
advertised-undo | C-_ | 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 | Erase 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 | M-s | Center line that cursor is on.
center-paragraph | (none) | Center paragraph that cursor is on.
center-region | (none) | Center currently defined region.
comint-interrupt-subjob | C-c C-c | Terminate the current job.
comint-kill-input | C-c C-u | Erase current line.
comint-send-eof | C-c C-d | End of file character.
comint-stop-subjob | C-c C-z | Suspend current job.
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 and call-last-kbd-macro | M-n C-x e | Execute the last defined macro n times.
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 | C-M-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 read with C-x C-f.
find-file | C-x C-f | Find file and read it.
find-file-other-frame | C-x 5 f | Find a file in a new frame.
find-file-other-window | C-x 4 f | Find a file in the other 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 | C-M-\ | 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-keyboard-macro | (none) | Insert the macro you named into a file.
inverse-add-global-abbrev | C-x a i g | Type global abbreviation, then definition.
inverse-add-local-abbrev | C-x a i l | Type local abbreviation, then definition.
isearch-backward | C-r | Start incremental search backward.
isearch-backward-regexp | C-r | Same, but search for regular expression.
isearch-forward | C-s | Start incremental search forward.
isearch-forward-regexp | C-r | 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-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 | Mark page.
mark-paragraph | M-h | Mark paragraph.
mark-whole-buffer | C-x h | Mark 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-regexp | C-% Meta | Query-replace a regular expression.
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 (may hang terminal; use C-q to restart).
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 | C-M-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 . | Use characters from the beginning of the line up to the cursor column as the "fill prefix." This prefix is prepended to each line in the paragraph. Cancel the prefix by typing this command in column 1.
set-mark-command | C-@ or C-Space | Mark the beginning (or end) of a region.
shell | (none) | Start a shell buffer.
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 | C-M-o | Split line at cursor; indent to column of cursor.
split-window-vertically | C-x 2 | Divide the current window into two, one on top of the other.
split-window-horizontally | C-x 3 | Divide the current window into two, side by side.
start-kbd-macro | C-x ( | Start macro definition.
suspend-emacs | C-z | Suspend Emacs (use exit or 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 the other window.
text-mode | (none) | Exit indented text mode; return to text mode.
transpose-chars | C-t | Transpose two letters.
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.
universal-argument and start-kbd-macro | C-u C-x ( | Execute last macro defined, then add keystrokes to it.
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 9. The vi, ex, and vim Editors

The vi and ex editors are the "standard" editors on Unix systems. You can count on there being some version of them, no matter what Unix flavor you are using. The two editors are in fact the same program; based on how it was invoked, the editor enters full-screen mode or line mode.

vim is a popular extended version of vi. On some Linux distributions, the vi command invokes vim in a vi-compatible mode.

This chapter presents the following topics:

  • Conceptual overview

  • Command-line syntax

  • Review of vi operations

  • Alphabetical list of keys in command mode

  • vi commands

  • vi configuration

  • ex basics

  • Alphabetical summary of ex commands

vi is pronounced "vee eye."

Besides the original Unix vi, there are a number of freely available vi clones (including vim). Both the original vi and the clones are covered in Learning the vi Editor (O'Reilly).


Section 9.1. Conceptual Overview

9.1. Conceptual Overview

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

The vi editor operates in two modes: command mode and insert mode. The dual modes make 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. However, vim supports both ways of editing, through the insertmode option.

vi is based on an older line editor called ex. (ex, in turn, was developed by Bill Joy at the University of California, Berkeley, from the primordial Unix line editor, ed.) A user can invoke powerful editing capabilities within vi by typing a colon (:), entering an ex command, and pressing the Enter 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 such 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 offers many extra features, and optionally changes some of the basic features of vi, most notoriously changing the undo key to support multiple levels of undo.

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 internal help system that you can use to learn more about the things we just couldn't fit into this chapter. See http://www.vim.org for more information.


Section 9.2. Command-Line Syntax

9.2. Command-Line Syntax

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

     vi [options] file
     vi [options] +num file
     vi [options] +/pattern file

You can open file for editing, optionally at line num or at the first line matching pattern. If no file is specified, vi opens with an empty buffer.

9.2.1. Command-Line Options

Because vi and ex are the same program, they share the same options. However, some options only make sense for one version of the program. Options specific to vim are so marked.

+[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. (For ex, fails if nowrapscan is set in your .exrc startup file, since ex starts editing at the last line of a file.)

-b

Edit the file in binary mode. {vim}

-c command

Run the given ex command upon startup. Only one -c option is permitted for vi; vim accepts up to 10. 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}

-C

vim: Start the editor in vi-compatible mode.

-d

Run in diff mode. Can also be invoked by running the command vimdiff. {vim}

-D

Debugging mode for use with scripts. {vim}

-e

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

-h

Print help message, then exit. {vim}

-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).

-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

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

-M

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

-n

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

--noplugin

Do not load any plug-ins. {vim}

-N

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

-o[num]

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

-O[num]

Start vim with num open windows arranged horizontally (split vertically) on the screen. {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.

-R

Edit files read-only.

-s

Silent; do not display prompts. Useful when running a script. This behavior also can be set through the older - option. For vim, only applies when used together with -e.

-s scriptfile

Read and execute commands given in the specified scriptfile as if they were typed in from the keyboard. {vim}

-S commandfile

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

-t tag

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

-T type

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

-u file

Read configuration information from the specified resource file instead of default .vimrc resource file. 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 for vi).

--version

Print version information, then exit. {vim}

-V[num]

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 rows

Set the window size so rows lines at a time are displayed; useful when editing over a slow dial-up line (or long distance Internet connection). Older versions of vi do not permit a space between the option and its argument. vim does not support this option.

-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}

-x

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

[*] The crypt command's encryption is weak. Don't use it for serious secrets.

-y

Modeless vi; run vim in insert mode only, without a command mode. {vim}

-Z

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

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.

You can exit ex in several ways:

:x

Exit (save changes and quit).

:q!

Quit without saving changes.

:vi

Enter the vi editor.


Section 9.3. Review of vi Operations

9.3. Review of vi Operations

This section provides a review of the following:

  • vi modes

  • Syntax of vi commands

  • Status-line commands

9.3.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 Unix shell

  • Save the current version of the file

  • Exit vi

9.3.2. Insert Mode

In insert mode, you can enter new text in the file. You normally enter insert mode with the i command. Press the Escape key to exit insert mode and return to command mode. The full list of commands that enter insert mode is provided later, in the section Insert Commands."

9.3.4. Syntax of vi Commands

In vi, editing commands have the following general form:

    [n] operator[m] motion

The basic editing operators are:

c

Begin a change.

d

Begin a edeletion.

y

Begin a yank (or copy).

If the current line is the object of the operation, the motion is the same as the operator: cc, dd, yy. Otherwise, the editing operators act on objects specified by cursor-movement commands or pattern-matching commands. (For example, cf. changes up to the next period.) 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 of operation can be any of the following text blocks:

word

Includes characters up to a whitespace character (space or tab) or punctuation mark. A capitalized object is a variant form that recognizes only whitespace.

sentence

Is up to ., !, or ?, followed by two spaces.

paragraph

Is up to the next blank line or paragraph macro defined by the para= option.

section

Is up to the next nroff/troff section heading defined by the sect= option.

motion

Is up to the character or other text object as specified by a motion specifier, including pattern searches.

9.3.4.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.

y]]

Copy up to the next section.

cG

Change to the end of the edit buffer.

More commands and examples may be found in the section Changing and Deleting Text," later in this chapter

9.3.4.2 Visual mode (vim only)

vim provides an additional facility, "visual mode." This allows you to highlight blocks of text which then become the object of edit commands such as deletion or saving (yanking). Graphical versions of vim allow you to use the mouse to highlight text in a similar fashion. See the vim help file visual.txt for the full story.

v

Select text in visual mode one character at a time.

V

Select text in visual mode one line at a time.

Ctrl-V

Select text in visual mode in blocks.

9.3.5. 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 edit these commands:

/

Search forward for a pattern.

?

Search backward for a pattern.

:

Invoke an ex command.

!

Invoke a Unix command that takes as its input an object in the buffer and replaces it with output from the command. You type a motion command after the ! to describe what should be passed to the Unix command. The command itself is entered on the status line.

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


Section 9.4. vi Commands

9.4. vi Commands

vi supplies a large set of single-key commands when in command mode. vim supplies additional multi-key commands.

9.4.1. 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 used after an operator. The operator works on the text that is moved.

9.4.1.1 Character

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

9.4.1.2 Text

Command | Action
w, b | Forward, backward by "word" (letters, numbers, and underscore make up words).
W, B | Forward, backward by "WORD" (only whitespace separates items).
e | End of word.
E | End of WORD.
ge | End of previous word. {vim}
gE | End of previous WORD. {vim}
), ( | Beginning of next, current sentence.
}, { | Beginning of next, current paragraph.
]], [[ | Beginning of next, current section.
][, [ ] | End of next, current section. {vim}

9.4.1.3 Lines

Long lines in a file may show up on the screen as multiple lines. (They wrap around from one screen line to the next.) While most commands work on the lines as defined in the file, a few commands work on lines as they appear on the screen. The vim option wrap allows you to control how long lines are displayed.

Command | Action
0, $ | First, last position of current line.
^, _ | First nonblank character of current line.
+, - | First nonblank character of next, previous line.
Enter | First nonblank character of next line.
num| | Column num 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 (Home position).
M | Middle line of screen.
L | Last line of screen.
numH | num lines after top line.
numL | num lines before last line.

9.4.1.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 screen.
z Enter | 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).
Ctrl-R | vi: Redraw screen (without scrolling).
 | vim: Redo last undone change.

9.4.1.5 Searches

Command | Action
/pattern | Search forward for pattern. End with Enter.
/pattern/+num | Go to line num after pattern.
?pattern | Search backward for pattern. End with Enter.
?pattern?-num | Go to line num before pattern.
:noh | Suspend search highlighting until next search. {vim}.
n | Repeat previous search.
N | Repeat search in opposite direction.
/ | Repeat previous search forward.
? | Repeat previous search backward.
* | 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}
% | Find match of current parenthesis, brace, or bracket.
fx | Move cursor forward to x on current line.
Fx | Move cursor backward to x on current line.
tx | Move cursor forward to character before x in current line.
Tx | Move cursor backward to character after x in current line.
, | Reverse search direction of last f, F, t, or T.
; | Repeat last f, F, t, or T.

9.4.1.6 Line Numbering

Command | Action
Ctrl-G | Display current line number.
gg | Move to first line in file. {vim}
numG | Move to line number num.
G | Move to last line in file.
:num | Move to line number num.

9.4.1.7 Marks

Command | Action
mx | Place mark x at current position.
`x | (backquote) Move cursor to mark x.
'x | (apostrophe) Move to start of line containing x.
`` | (backquotes) Return to position before most recent jump.
'' | (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}
`0 | Position where you last exited vim. {vim}
:marks | List active marks. {vim}

9.4.2. Insert Commands

Command | Action
a | Append after cursor.
A | Append to end of line.
c | Begin change operation.
C | Change to end of line.
gI | Insert at beginning of line. {vim}
i | Insert before cursor.
I | Insert at beginning of line.
o | Open a line below cursor.
O | Open a line above cursor.
R | Begin overwriting text.
s | Substitute a character.
S | Substitute entire line.
ESC | Terminate insert mode.

The following commands work in insert mode.

Command | Action
Backspace | Delete previous character.
Delete | Delete current character.
Tab | Insert a tab.
Ctrl-A | Repeat last insertion. {vim}
Ctrl-D | Shift line left to previous shift width. {vim}
Ctrl-E | Insert character found just below cursor. {vim}
Ctrl-H | Delete previous character (same as Backspace).
Ctrl-I | Insert a tab.
Ctrl-K | Begin insertion of multi-keystroke character.
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-U | Delete current line.
Ctrl-V | Insert next character verbatim.
Ctrl-W | Delete previous word.
Ctrl-Y | Insert character found just above cursor. {vim}
Ctrl-[ | (Escape) Terminate insert mode.

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

9.4.3. Edit Commands

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

9.4.3.1 Changing and Deleting Text

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

Command | Action
cw | Change word.
cc | Change line.
c$ | Change text from current position to end of line.
C | Same as c$.
dd | Delete current line.
numdd | Delete num lines.
d$ | Delete text from current position to end of line.
D | Same as d$.
dw | Delete a word.
d} | Delete up to next paragraph.
d^ | Delete back to beginning of line.
d/pat | 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 (but 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 with new text (overwrite), beginning at cursor. Escape ends replace mode.
s | Substitute character.
4s | Substitute four characters.
S | Substitute entire line.
u | Undo last change.
Ctrl-R | Redo last change. {vim}
U | Restore current line.
x | Delete current cursor position.
X | Delete back one character.
5X | Delete previous five characters.
. | Repeat last change.
~ | Reverse case and move cursor right.
Ctrl-A | Increment number under cursor. {vim}
Ctrl-X | Decrement number under cursor. {vim}

9.4.3.2 Copying and Moving

Register names are the letters a-z. Uppercase names append text to the corresponding register.

Command | Action
Y | Copy current line.
yy | Copy current line.
"xyy | Copy current line to register x.
ye | Copy text to end of word.
yw | Like ye, but include the whitespace after the word.
y$ | Copy rest of line.
"xdd | Delete current line into register x.
"xd | Delete into register x.
"xp | Put contents of register x.
y]] | Copy up to next section heading.
ye | Copy to end of word.
"xp | Put contents of register x.
J | Join current line to next line.
gJ | Same as J, but without inserting a space. {vim}
:j | Same as J.
:j! | Same as gJ.

9.4.4. Saving and Exiting

Writing a file means overwriting the file with the current text.

Command | Action
ZZ | Quit vi, writing the file only if changes were made.
:x | Same as ZZ.
:wq | Write file and quit.
:w | Write file.
:w file | Save copy to file.
:n,mw file | Write lines n to m to new file.
:n,mw >> file | Append lines n to m to existing file.
:w! | Write file (overriding protection).
:w! file | Overwrite file with current text.
:w %.new | Write current buffer named file as file.new.
:q | Quit vi (fails if changes were made).
:q! | Quit vi (discarding edits).
Q | Quit vi and invoke ex.
:vi | Return to vi after Q command.
% | Replaced with current filename in editing commands.
# | Replaced with alternate filename in editing commands.

9.4.5. Accessing Multiple Files

Command | Action
:e file | Edit another file; current file becomes alternate.
:e! | Return to version of current file at time of last write.
:e + file | Begin editing at end of file.
:e +num file | Open file at line num.
:e # | Open to previous position in alternate file.
:ta tag | Edit file at location tag.
:n | Edit next file in the list of files.
:n! | Force next file.
:n files | Specify new list of files.
:rewind | Edit first file in the list.
Ctrl-G | Show current file and line number.
:args | Display list of files to be edited.
:prev | Edit previous file in the list of files.

9.4.6. Window Commands

The following table lists common commands for controlling windows in vim. See also the split, vsplit, and resize commands in the section Alphabetical Summary of ex Commands," later in this chapter. 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. With file, edit that file in the new window.
:sv [file] | Same as :sp, but make new window read-only.
:sn [file] | Edit next file in file list in new window.
:vsp [file] | Like :sp, but split vertically instead of horizontally.
:clo | Close current window.
:hid | Hide current window, unless it is the only visible window.
:on | Make current window the only visible one.
:res num | Resize window to num 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.

9.4.7. Interacting with the System

Command | Action
:r file | Read in contents of file after cursor.
:r !command | Read in output from command after current line.
:numr !command | Like above, but place after line num (0 for top of file).
:!command | Run command, then return.
!motion command | Send the text covered by motion to Unix command; replace with output.
:n,m! command | Send lines n-m to command; replace with output.
num!!command | Send num lines to Unix command; replace with output.
:!! | Repeat last system 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.

9.4.8. Macros

Command | Action
:ab in out | Use in as abbreviation for out in insert mode.
:unab in | Remove abbreviation for in.
:ab | List abbreviations.
:map string sequence | Map characters string as sequence of commands. Use #1, #2, etc., for the function keys.
:unmap string | Remove map for characters string.
:map | List character strings that are mapped.
:map! string sequence | Map characters string to input mode sequence.
:unmap! string | Remove input mode map (you may need to quote the character with Ctrl-V).
:map! | List character strings that are mapped for 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. Use @@ to repeat the last @ command.

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

^A ^K ^O ^W ^X ^_ ^\

Symbols

_ * \ = #

NOTE

The = is used by vi if Lisp mode is set. Different versions of vi may use some of these characters, so test them before using.

vim does not use ^K, ^_, _, or \.

9.4.9. Miscellaneous Commands

Command | Action
< | Shift text described by following motion command left by one shiftwidth. {vim}
> | Shift text described by following motion command right by one shiftwidth. {vim}
<< | Shift line left one shift width (default is eight spaces).
>> | Shift line right one shift width (default is eight spaces).
>} | Shift right to end of paragraph.
<% | Shift left until matching parenthesis, brace, or bracket. (Cursor must be on the matching symbol.)
= = | Indent line in C-style, or using program specified in equalprg option. {vim}
g | Start many multiple character commands in vim.
K | Look up word under cursor in manpages (or program defined in keywordprg). {vim}
^O | Return to previous jump. {vim}
q | Record keystrokes. {vim}
^Q | Same as ^V. {vim} (On some terminals, resume data flow.)
^T | Return to the previous location in the tag stack. (vim)
^] | 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.


Section 9.5. vi Configuration

9.5. vi Configuration

This section describes the following:

  • The :set command

  • Options available with :set

  • Sample .exrc file

9.5.1. The :set Command

The :set command allows you to 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 does not need to be typed if the command is put in .exrc:

Command | Action
:set x | Enable boolean option x, show value of other options.
:set nox | Disable option x.
:set x=value | Give value to option x.
:set | Show changed options.
:set all | Show all options.
:set x? | Show value of option x.

9.5.2. Options Used by :set

Table 9-1 contains brief descriptions of the important set command options. In the first column, options are listed in alphabetical order; if the option can be abbreviated, that abbreviation is shown in parentheses. The second column shows the default setting. The last column describes what the option does, when enabled.

This table lists set options for vi, with the addition of important vim options. Other versions of vi may have more or fewer or different options. See your local documentation, or use :set all to see the full list. Options that receive a value are marked with an =.

Table 9-1. :set Options

Option

Default

Description

autoindent (ai)

noai

In insert mode, indent each line to the same level as the line above or below. Use with the shiftwidth option.

autoprint (ap)

ap

Display changes after each editor command. (For global replacement, display last replacement.)

autowrite (aw)

noaw

Automatically write (save) the file if changed before opening another file with a command such as :n, or before giving Unix 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}

beautify (bf)

nobf

Ignore all control characters during input (except tab, newline, or formfeed).

backupext= (bex)

~

String to append to filenames for backup files. {vim}

cindent (cin)

nocindent

In insert mode, indent each line relative to the one above it, as is appropriate for C or C++ code. {vim}

compatible (cp)

cp

Make vim behave more like vi. Default is nocp when a ~/.vimrc file is found. {vim}

directory (dir)

/tmp

Name of directory in which ex/vi stores buffer files. (Directory must be writable.) This can be a comma-separated list for vim.

edcompatible

noedcompatible

Remember the flags used with the most recent substitute command (global, confirming) and use them for the next substitute command. Despite the name, no version of ed actually does this.

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 empty (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 pattern. Use :nohlsearch to remove highlighting. {vim}

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 end character is a tab or a space.)

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}

novice

nonovice

Require the use of long ex command names, such as copy or read.

number (nu)

nonu

Display line numbers on left of screen during editing session.

open

open

Allow entry to open or visual mode from ex. Although not in vim, this option has traditionally been in vi, and may be in your version of vi.

optimize (opt)

noopt

Abolish carriage returns at the end of lines when printing multiple lines; speed output on dumb terminals when printing lines with leading whitespace (spaces or tabs).

paragraphs (para)

IPLPPPQPP LIpplpipnpbp

Define paragraph delimiters for movement by { or }. The pairs of characters in the value are the names of troff macros that begin paragraphs.

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}

prompt

prompt

Display the ex prompt ( : ) when vi 's Q command is given.

readonly (ro)

noro

Any writes (saves) of a file fail unless you use ! after the write (works with w, ZZ, or autowrite).

redraw (re)

vi redraws the screen whenever edits are made. noredraw is useful at slow speeds on a dumb terminal: the screen isn't fully updated until you press Escape. Default depends on line speed and terminal type.

remap

remap

Allow nested map sequences.

report=

5

Display a message on the status 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]

Number of lines to scroll with ^D and ^U commands.

sections= (sect)

SHNHH HUnhsh+c

Define section delimiters for [ [ and ] ] movement. The pairs of characters in the value are the names of 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 environment, which varies on different systems.

shiftwidth= (sw)

8

Define number of spaces used when the indent in increased or decreased.

showmatch (sm)

nosm

In vi, when ) or } is entered, cursor moves briefly to matching ( or {. (If no match, rings the error message bell.) Very useful for programming.

showmode

noshowmode

In insert mode, display a message on the prompt line indicating the type of insert you are making. For example, "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 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 (zero) means that all characters are significant.

tags=

tags /usr/lib/tags

Define pathname of files containing tags. (See the Unix ctags command.) (By default, vi searches the file tags in the current directory and /usr/lib/tags.)

tagstack

tagstack

Enable stacking of tag locations on a stack. (Solaris vi and vim.)

term=

Set terminal type.

terse

noterse

Display shorter error messages.

textwidth= (tw)

0

The maximum width of text to be inserted; longer lines are broken after whitespace. Default (zero) disables this feature, in which case wrapmargin is used. {vim}

timeout (to)

timeout

Keyboard maps timeout after 1 second.[a]

timeoutlen= (tm)

1000

Number of milliseconds after which keyboard maps timeout. Default value of 1000 provides traditional vi behavior. {vim}

ttytype=

Set terminal type. This is just another name for term.

undolevels= (ul)

1000

Number of changes that can be undone. {vim}

warn

warn

Display the warning 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.

wrap

When on, long lines wrap on the screen. When off, only the first part of the line is displayed. {vim}

wrapmargin (wm)

0

Define right margin. If greater than zero, vi automatically inserts 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 successfully written, unless the backup option is set. {vim}

[a] When you have mappings of several keys (for example, :map zzz 3dw), you probably want to use notimeout. Otherwise, you need to type zzz within 1 second. When you have an insert mode mapping for a cursor key (for example, :map! ^[OB ^[ja), you should use timeout. Otherwise, vi won't react to Escape until you type another key.

9.5.3. Sample .exrc File

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

     set nowrapscan                      " Searches don't wrap at end of file
     set wrapmargin=7                    " Wrap text at 7 columns from right margin
     set sections=SeAhBhChDh nomesg      " Set troff macros, disallow message
     map q :w^M:n^M                      " Alias to move to next file
     map v dwElp                         " Move a word
     ab ORA O'Reilly Media, Inc.         " Input shortcut

NOTE

The q alias isn't needed for vim, which has the :wn command. The v alias would hide the vim command v, which enters character-at-a-time visual-mode operation.


Section 9.6. ex Basics

9.6. ex Basics

The ex line editor serves as the foundation for the screen editor vi. Commands in ex work on the current line or on a range of lines in a file. Most often, you use ex from within vi. In vi, ex commands are preceded by a colon and entered by pressing Enter.

You can also invoke ex on its ownfrom the command linejust as you would invoke vi. (You could execute an ex script this way.) You can also use the vi command Q to quit the vi editor and enter ex.

9.6.1. 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. Execute the command by pressing the Enter key. address is the line number or range of lines that are the object of command. options and addresses are described below. ex commands are described in the next section Alphabetical Summary of ex Commands."

You can exit ex in several ways:

:x

Exit (save changes and quit).

:q!

Quit without saving changes.

:vi

Switch to the vi editor on the current file.

9.6.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 each be a line number or a symbol. Using ; instead of , sets the current line to x before interpreting y. The notation 1,$ addresses all lines in the file, as does %.

9.6.3. Address Symbols

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

See Chapter 7 for more information on using patterns.

9.6.4. Options

!

Indicates a variant form of the command, overriding the normal behavior. The ! must come immediately after the command.

count

The number of times the command is to be repeated. Unlike in vi commands, count cannot precede the command, because a number preceding an ex command is treated as a line address. For example, d3 deletes three lines beginning with the current line; 3d deletes line 3.

file

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


Section 9.7. Alphabetical Summary of ex Commands

9.7. 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.

abbreviate
     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 ^V followed by Enter.

    :ab ora O'Reilly Media, Inc.
    :ab id Name:^MRank:^MPhone:

append
    [address] a[!]
    text
    .

Append new text at specified address, or at present address if none is specified. Add a ! to toggle the autoindent setting that is used during input. That is, 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
    args file ...

Print the members of the argument list (files named on the command line), with the current argument printed in brackets ([ ]).

The second syntax is for vim, which allows you to reset the list of files to be edited.

bdelete
    [num] bd[!] [num]

Unload buffer num 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
    [num] b[!] [num]

Begin editing buffer num 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 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}

cd
    cd dir
    chdir dir

Change current directory within the editor to dir.

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 (short for "to") is a synonym for copy.

Example

    :1,10 co 50        Copy first 10 lines to just after line 50

delete
    [address] d [register]

Delete the lines included in address. If register is specified, save or append the text to the named register. Register names are the lowercase letters a-z. Uppercase names append text to the corresponding register.

Examples

    :/Part I/,/Part II/-1d      Delete to line above "Part II"
    :/main/+d     Delete line below "main"
    :.,$d x       Delete from this line to last line into
                                          register x

edit
    e[!] [+num] [filename]

Begin editing on filename. If no filename is given, start over with a copy of the current file. Add a ! to edit the new file even if the current file has not been saved since the last change. With the +num argument, begin editing on line num. Or num may be a pattern, of the form /pattern.

Examples

    :e file          Edit file in current editing buffer
    :e +/^Index #    Edit alternate file at pattern match
    :e!              Start over again on current file

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 "not edited" 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. A # can be used to indicate the alternate 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 later can 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 which contain pattern or, if address is specified, on all lines within that range. If commands are not specified, print all such lines. Add a ! to execute commands on all lines not containing pattern. See also v.

Examples

    :g/Unix/p            Print all lines containing "Unix"
    :g/Name:/s/tom/Tom/   Change "tom" to "Tom" on all lines
                                        containing "Name:"

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[!]
    text
    .

Insert 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. Terminate input of new text by entering a line consisting of just a period.

join
    [address] j[!] [count]

Place the text in the specified range on one line, with whitespace adjusted to provide two space characters after a period (.), no space characters before a ), and one space 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

Same as mark; see mark, later in this 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}

list
     [address] l [count]

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

map
    map[!] [string commands]

Define a keyboard macro named string as the specified sequence of commands. string is usually a single character, or the sequence #num, 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

NOTE

vim has K and q commands, which the above aliases would hide.

mark
    [address] ma char

Mark the specified line with char, a single lowercase letter. Return later to the line with 'x (where x is the same as 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 set commands for changed ex options and key mappings. This saves the current option settings, allowing you to restore them later.

move
    [address] m destination

Move the lines specified by address to the destination address.

Example

    :.,/Note/m /END/        Move text block to after line containing "END"

new
    [count] new

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

next
    num[!] [[+num] 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. With the +num argument, begin editing on line num. Or num may be a pattern, of the form /pattern.

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.

only
    on [!]

Make the current window be the only one on the screen. Windows open on modified buffers are not removed from the screen (hidden), unless you also use the ! character. {vim}

open
    [address] o [/pattern/]

Enter open mode (vi) at the lines specified by address, or at the lines matching pattern. Exit open mode with Q. Open mode lets you use the regular vi commands, but only one line at a time. It can be useful on slow dial-up lines (or on very distant Internet ssh connections).

preserve
    pre

Save the current editor buffer as though the system were about to crash.

previous
    prev[!]

Edit the previous file from the command-line argument list. {vim}

print
    [address] p [count]

Print the lines specified by address. count specifies the number of lines to print, starting with address. P is another abbreviation.

Example

    :100;+5p       Show line 100 and the next five lines

put
    [address] pu [char]

Restore previously deleted or yanked lines from named register specified by char, to the line specified by address. If char is not specified, the last deleted or yanked text is restored.

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. vim only closes the editing window if there are still other windows open on the screen.

read
    [address] r filename

Copy the text of filename after the line specified by address. If filename 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 shell command into the text after the line specified by address.

Example

    :$r !spell %            Place results of spell checking at end of file

recover
    rec [file]

Recover file from the system save area.

redo
    red

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

resize
    res [[±]num]

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

rewind
    rew[!]

Rewind argument list and begin editing the first file in the list. Add a ! to rewind even if the current file has not been saved since the last change.

right
    [address] ri [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}

sbnext
    [count] sbn [count]

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

sbuffer
    [num] sb [num]

Split the current window and begin editing buffer num 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}

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 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. The form set option? displays the value of option. See the list of set options in the section The :set Command," earlier in this chapter.

Examples

    :set nows wm=10

    :set all

shell
    sh

Create a new shell. Resume editing when the shell terminates.

snext
    [count] sn [[+num] filelist]

Split the current window and begin editing the next file from the command-line argument list. If count is provided, edit the count'th 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 num. Alternately, num may be a pattern of the form /pattern. {vim}

source
    so file

Read (source) and execute ex commands from file.

Example

    :so $HOME/.exrc

split
    [count] sp [+num] [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 num. num may also be a pattern of the form /pattern. {vim}

sprevious
    [count] spr [+num]

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'th previous file. With the +num argument, begin editing on line num. num may also be a pattern of the form /pattern. {vim}

stop
    st

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

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

Replace the first instance of pattern on each of 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. See additional examples in Chapter 7.

Options

c

Prompt for confirmation before each change.

g

Substitute all instances of pattern on each line (global).

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 "Fortran" on next three lines
    :g/^[0-9][0-9]*/s//Line &:/   For every line beginning with one or
                                                more digits, add "Line" and a colon

suspend
    su

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

sview
    [count] sv [+num] [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 address. t is equivalent to copy.

Example

    :%t$       Copy the file and add it to the end

tag
    [address] ta tag

In the tags file, locate the file and line matching tag, and start editing there.

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[!] string

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

v
    [address] v/pattern/[command]

Execute command on all lines not containing pattern. If command is 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 and date of last change.

view
    vie[[+num] 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. Return to ex mode with Q. type can be one of -, ^, or . (See the z command). count specifies an initial window size.

visual
    vi [+ num] file

Begin editing file in visual mode (vi), optionally at line num.

vsplit
    [count] vs [+num] [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[!] [[+num] filename]

Write current buffer and open next file in argument list, or the count'th next file if specified. If filename is specified, edit it next. With the +num argument, begin editing on line num. num may also be a pattern of the form /pattern. {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, append lines to the end of the specified file. Add a ! to force the editor to write over any current contents of file.

Examples

     :1,10w name_list      Copy first 10 lines to file name_list
     :50w >> name_list       Now append line 50

write
    [address] w !command

Write lines specified by address to command.

Example

    :1,66w !pr -h myfile | lp           Print first page of file

wq
    wq[!]

Write and quit the file in one movement. The file is always written. 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}

X
    X

Prompt for an encryption key. This command 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] y [char] [count]

Place lines specified by address in named register char. Register names are the lowercase letters a-z. Uppercase names append text to the corresponding register. If no char is given, place lines in general register. count specifies the number of lines to yank, starting with address.

Example

    :101,200 ya a      Copy lines 100-200 to register "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 the top of the window (default).

-

Place specified line at the bottom of the window.

.

Place specified line in the center of the window.

^

Print the previous window.

=

Place specified line in the center of the window and leave the current line at this line.

!
    [address] !command

Execute Unix command in a shell. If address is specified, use the lines contained in address as standard input to command, and replace the lines with the output and error output. (This is called filtering the text through the command.)

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 line indicated by address. Default is line number of the last line.

< >
     [address] < [count]
     [address] > [count]

Shift lines specified by address either left (<) or right (>). Only leading spaces and tabs are added or removed when shifting lines. count specifies the number of lines to shift, starting with address. The shiftwidth option controls the number of columns that are shifted. Repeating the < or > increases the shift amount. For example, :>>> shifts three times as much as :>.

address

    address

Print the lines specified in address.

Enter

Print the next line in the file. (For ex only; not from the : prompt in vi.)

@
    [address] @ [char]

Execute contents of register specified by char. If address is given, move cursor to the specified address first. If char is @, repeat the last @ command.

&
    [address] & [options] [count]

Repeat the previous substitute (s) command. count specifies the number of lines on which to substitute, starting with address. options are the same as for the substitute command.

Examples

    :s/Overdue/Paid/           Substitute once on current line
    :g/Status/&            Redo substitution on all "Status" lines

~
    [address] ~ [count]

Replace the last-used regular expression (even if from a search, and not from an s command) with the replacement pattern from the most recent s (substitute) command. This is rather obscure; see Chapter 6 of Learning the vi Editor (O'Reilly) for details.


Chapter 10. The sed Editor

The sed "stream editor" is one of the most prominent text-processing tools on Unix and Linux. It is most often used for performing simple substitutions on data streams going through pipelines, but sed scripts can be written to do much more.

This chapter presents the following topics:

  • Conceptual overview of sed

  • Command-line syntax

  • Syntax of sed commands

  • Group summary of sed commands

  • Alphabetical summary of sed commands

The version of sed provided with Linux systems is the GNU version written by the Free Software Foundation; its home page is http://www.gnu.org/software/sed/sed.html. For more information on sed, see sed & awk (O'Reilly).


Section 10.1. Conceptual Overview

10.1. Conceptual Overview

The stream editor, sed, is a non-interactive editor. It interprets a script and performs the actions in the script. sed is stream-oriented because, like 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 or pipe, but it can also be taken from the keyboard. Output goes to the screen by default, but it can be captured in a file or sent through a pipe instead. GNU sed can edit files that use multibyte character sets.

10.1.1. Typical Uses of sed

  • Editing one or more files automatically.

  • Simplifying repetitive edits to multiple files.

  • Writing conversion programs.

10.1.2. sed Operation

sed operates as follows:

  • Each line of input is copied into a pattern space, an internal buffer where editing operations are performed.

  • 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 and address tests are applied to the current line in the pattern space, not the original input line.

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

  • sed also maintains the hold space, a separate buffer that can be used to save data for later retrieval.


Section 10.2. Command-Line Syntax

10.2. Command-Line Syntax

The syntax for invoking sed has two forms:

    sed [-n] [-e] 'command' file(s)
    sed [-n]  -f  scriptfile file(s)

The first form allows you to specify an editing command on the command line, surrounded by single quotes. The second form allows you to specify a scriptfile, a file containing sed commands. Both forms may be used together, and they may be used multiple times. If no file (s) is specified, sed reads from standard input.

10.2.1. Standard Options

The following options are recognized:

-n

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

-e cmd

Next argument is an editing command. Necessary if multiple scripts or commands are specified.

-f file

Next argument is a file containing editing commands.

If the first line of the script is #n, sed behaves as if -n had been specified.

Multiple -e and -f options may be provided, and they may be mixed. The final script consists of the concatenation of all the script and file arguments.

10.2.2. GNU sed Options

GNU sed accepts a number of additional command-line options, as well as long-option equivalents for the standard options. The GNU sed options are:

-e cmd, --expression cmd

Use cmd as editing commands.

-f file, --file file

Obtain editing commands from file.

--help

Print a usage message and exit.

-i[suffix], --in-place[=suffix]

Edit files in place, overwriting the original file. If optional suffix is supplied, use it for renaming the original file as a backup file. See the GNU sed online Info documentation for the details.

-l len, --line-length len

Set the line length for the l command to len characters.

-n, --quiet, --silent

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

--posix

Disable all GNU extensions. Setting POSIXLY_CORRECT in the environment merely disables those extensions that are incompatible with the POSIX standard.

-r, --regex-extended

Use Extended Regular Expressions instead of Basic Regular Expressions. See Chapter 7 for more information.

-s, --separate

Instead of considering the input to be one long stream consisting of the concatenation of all the input files, treat each file separately. Line numbers start over with each file, the address $ refers to the last line of each file, files read by the R command are rewound, and range addresses (/x/,/y/) may not cross file boundaries.

-u, --unbuffered

Buffer input and output as little as possible. Useful for editing the output of tail -f when you don't want to wait for the output.

--version

Print the version of GNU sed and a copyright notice, and then exit.


Section 10.3. Syntax of sed Commands

10.3. Syntax of sed Commands

sed commands have the general form:

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

commands consist of a single letter or symbol; they are described later, by group and alphabetically. 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 next.

10.3.1. Pattern Addressing

A sed command can specify zero, one, or two addresses. In POSIX sed, an address has one of the forms in the following table. Regular expressions are described in Chapter 7. 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.

Address | Meaning
/pattern/ | Lines that match pattern.
\;pattern; | Like previous, but use semicolon as the delimiter instead of slash. Any character may be used. This is useful if pattern contains multiple slash characters.
n | Line number n.
$ | The last input line.

If the command specifies: | Then the command is applied to:
No address | Each input line.
One address | Any line matching the address. Some commands accept only one address: a, i, r, q, and =.
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.

GNU sed allows additional address forms:

Address | Meaning
/pattern/i | Match pattern, ignoring case. I may be used instead of i.
/pattern/m | Match pattern, allowing ^ and $ to match around an embedded newline. M may be used instead of m.
0,/pattern/ | Similar to 1,/pattern/, but if line 1 matches pattern, it will end the range.
address,+n | Matches line matching address, and the n following lines.
address~incr | Matches line matching address and every incr lines after it. For example, 42~3 matches 42, 45, 48, and so on.

10.3.2. Pattern Addressing Examples

Command | Action performed
s/xx/yy/g | Substitute on all lines (all occurrences).
/BSD/d | Delete lines containing BSD.
/^BEGIN/,/^END/p | Print between 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.

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

    [/pattern/[,/pattern/]]{
    command1

    command2
    }

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

10.3.3. GNU sed Regular Expression Extensions

With the -r option, GNU sed uses Extended Regular Expressions instead of Basic Regular expressions. (See Chapter 7 for more information.) However, even without -r, you can use additional escape sequences for more powerful text matching. The following escape sequences are valid only in regular expressions:

\b

Matches on a word boundary, where of the two surrounding characters (x\by), one is a word-constituent character and the other is not.

\B

Matches on a non-word boundary, where both of the two surrounding characters (x\by) are either word-constituent or not word-constituent.

\w

Matches any word-constituent character (i.e., a letter, digit, or underscore).

\W

Matches any non-word-constituent character (i.e., anything that is not a letter, digit, or underscore).

\`

Matches the beginning of the pattern space. This is different from ^ when the m modifier is used for a pattern or the s command.

\'

Matches the end of the pattern space. This is different from $ when the m modifier is used for a pattern or the s command.

The following escape sequences may be used anywhere.

\a

The ASCII BEL character.

\f

The ASCII formfeed character.

\n

The ASCII newline character.

\r

The ASCII carriage-return character.

\v

The ASCII vertical tab character.

\dnn

The character whose ASCII decimal value is nn.

\onn

The character whose ASCII octal value is nn.

\xnn

The character whose ASCII hexadecimal value is nn.


Section 10.4. Group Summary of sed Commands

10.4. Group Summary of sed Commands

In the lists that follow, 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 section. Commands marked with a | are specific to GNU sed.

10.4.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 Unix tr).

10.4.2. Line Information

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

10.4.3. Input/Output Processing

Command | Action
e | Execute commands.
n | Skip current line and go to the next line.
r | Read another file's contents into the output stream.
R | Read one line from a file into the output.
w | Write input lines to another file.
W | Write first line in pattern space to another file.
q | Quit the sed script (no further output).
Q | Quit without printing the pattern space.
v | Require a specific version of GNU sed to run the script.

10.4.4. Yanking and Putting

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

10.4.5. Branching Commands

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

10.4.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.


Section 10.5. Alphabetical Summary of sed Commands

10.5. Alphabetical Summary of sed Commands

GNU sed lets you use the filenames /dev/stdin, /dev/stdout and /dev/stderr to refer to standard input, output, and error, respectively, for the r, R, w, and W commands and the w flag to the s command.

GNU-specific commands or extensions are noted with {G} in the command synopsis. When the GNU version allows a command to have two addresses, the command is performed for each input line within the range.

#
    #

Begin a comment in a sed script. Valid only as the first character of the first line. (Some versions, including GNU sed, 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. According to POSIX, sed must support labels that are unique in the first eight characters. GNU sed has no limit, but some older versions support up to only seven characters.

=
    [/pattern/]=
    [address1[,address2]]= {G}

Write to standard output the line number of each line addressed by pattern.

a
    [address]a\
    text
    [address1[,address2]]a \ {G}

    text

Append text following each line matched by address. If text goes over more than one line, newlines must be "hidden" by preceding them with a backslash. The text is terminated by the first newline that is not hidden 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.

The GNU version accepts two addresses and allows you to put the first line of text on the same line as the a command.

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]

Unconditionally transfer control 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 HTML tables; resume script after </table>:
    /<table/,/<\/table>/b

c
    [address1[,address2]]c\
    text

Replace (change) the lines selected by the address(es) with text. (See a for details on text.) When a range of lines is specified, all lines are replaced as a group by a single copy of text. The contents of the pattern space are, in effect, deleted, and no subsequent editing commands can be applied to the pattern space (or to text).

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 empty lines, including lines with just
    whitespace:
    /^[#tab]*$/d

D
    [address1[,address2]]D

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

Example

    # Strip multiple blank lines, leaving only one:
    /^$/{
    N
    /^\n$/D
    }

e
    [address1[,address2]]e [command] {G}

With command, execute the command and send the result to standard output. Without command, execute the contents of the pattern space as a command, and replace the pattern space with the results.

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 that a newline and the hold space are pasted to the end of the pattern space 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 a newline and then the contents of the pattern space 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
    [address]i\
    text
    [address1[,address2]]i \ {G}

    text

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

The GNU version accepts two addresses and allows you to put the first line of text on the same line as the i command.

Example

    /Item 1/i\
    The five items are listed below:

l
    [address1[,address2]]l
    [address1[,address2]]l [len] {G}

List the contents of the pattern space, showing nonprinting characters as ASCII codes. Long lines are wrapped. With GNU sed, len is the character position at which to wrap long lines. A value of 0 means to never break lines.

n
    [address1[,address2]]n

Read the 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 DocBook/XML, titles follow section tags. Suppose you are using a convention where each opening section tag is on a line by itself, with the title on the following line. To print all the section titles, invoke this script with sed -n:

    /<sect[1-4]/{
    n
    p
    }

N
    [address1[,address2]]N

Append the next input line to contents of pattern space; the new line is separated from the previous contents of the pattern space by a newline. (This command is designed to allow pattern matches across two lines.) By using \n to match the embedded newline, you can match patterns across multiple lines. See the Example under D.

Examples

Like the Example in n, but print the section tag line as well as header title:

    /<sect[1-4]/{
    N
    p
    }

Join two lines (replace newline with space):

    /<sect[1-4]/{
    N
    s/\n/ /
    p
    }

p
    [address1[,address2]]p

Print the addressed line(s). Note that this can result in duplicate output unless default output is suppressed by using #n or the -n command-line option. Typically used before commands that change control flow (d, n, b), which might prevent the current line from being output. See the Examples under h, n, and N.

P
    [address1[,address2]]P

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

Example

Suppose you have function references in two formats:

    function(arg1, arg2)
    function(arg1,
             arg2)

The following script changes argument arg2, regardless of whether it appears on the same line as the function name:

    s/function(arg1, arg2)/function(arg1, XX)/
    /function(/{
    N
    s/arg2/XX/
    P
    D
    }

q
    [address]q
    [address]q [value] {G}

Quit when address is encountered. The addressed line is first written to the output (if default output is not suppressed), along with any text appended to it by previous a or r commands. GNU sed allows you to provide value, which is used as the exit status.

Examples

Delete everything after the addressed line:

    /Garbled text follows:/q

Print only the first 50 lines of a file:

    50q

Q
    [address]Q [value] {G}

Quits processing, but without printing the pattern space. If value is provided, it is used as sed's exit status.

r
    [address]r file
    [address1[,address2]]r file {G}

Read contents of file and append to the output after the contents of the pattern space. There must be exactly one space between the r and the filename. The GNU version accepts two addresses.

Example

    /The list of items follows:/r item_file

R
    [address1[,address2]]R file {G}

Read one line of file and append to the output after the contents of the pattern space. Successive R commands read successive lines from 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. Any delimiter may be used. Use \ within pattern or replacement to escape the delimiter. The following flags can be specified (those marked with a | are specific to GNU sed):

n

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

e

If the substitution was made, execute the contents of the pattern space as a shell command and replaces the pattern space with the results.

g

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

i or I

Do a case-insensitive regular expression match.

m or M

Allow ^ and $ to match around a newline embedded in the pattern space.

p

Print the line if the substitution is successful. If several successful substitutions are successful, sed prints multiple copies of the line.

w file

Write the line to file if a replacement was done. In the traditional Unix sed, a maximum of 10 different files can be opened.

GNU sed allows you to use the special filenames /dev/stdout and /dev/stderr to write to standard output or standard error, respectively.

Within the replacement, GNU sed accepts special escape sequences, with the following meanings:

\L

Lowercase the replacement text until a terminating \E or \U.

\l

Lowercase the following character only.

\U

Uppercase the replacement text until a terminating \E or \L.

\u

Uppercase the following character only.

\E

Terminate case conversion from \L or \U.

Examples

Here are some short, commented scripts:

    # Change third and fourth quote to ( and ):
    /function/{
    s/"/)/4
    s/"/(/3
    }

    # Remove all quotes on a given line:
    /Title/s/"//g

    # Remove first colon and 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 successful substitutions have been made on addressed lines, and if so, branch to the line marked by :label. (See b and :.) If label is not specified, control branches to the bottom of the script. The t command is like a case statement in the C programming language or the various 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

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):

    #n
    /ID/{
    s/ID: .* Name: .* Rate: .*/&   Phone: ??/p
    t
    s/ID: .* Name: .*/&   Rate: ??   Phone: ??/p
    t
    s/ID: .*/&   Name: ????   Rate: ??   Phone: ??/p
    }

T
    [address1[,address2]]T [label] {G}

Like t, but only branches to label if there not any successful substitutions. (see b, t, and :). If label is not specified, control branches to the bottom of the script.

v
    [address1[,address2]]v [version] {G}

This command doesn't do anything. You use it to require GNU sed for your script. This works, because non-GNU versions of sed don't implement the command at all, and will therefore fail. If you supply a specific version, GNU sed fails if the required version is newer than the one executing the script.

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 exists, 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.

GNU sed allows you to use the special filenames /dev/stdout and /dev/stderr to write to standard output or standard error, respectively.

Example

    # Store HTML tables in  a file
    /<table/,/<\/table>/w tables.html

W
    [address1[,address2]]W file

Like w, but only writes the contents of the first line in the pattern space to the file.

x
    [address1[,address2]]x

Exchange the contents of the pattern space with the 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/i123456789/IABCDEFGHI/


Chapter 11. The gawk Programming Language

gawk is the GNU version of awk, a powerful utility often used for text and string manipulation within shell scripts, particularly when input data can be viewed as records and fields. awk is also an elegant and capable programming language that allows you to accomplish a lot with very little work.

This chapter presents the following topics:

  • Conceptual overview

  • Command-line syntax

  • Patterns and procedures

  • Built-in variables

  • Operators

  • Variables and array assignment

  • User-defined functions

  • gawk-specific facilities

  • Implementation limits

  • Group listing of awk functions and commands

  • Alphabetical summary of awk functions and commands

  • Source code

For more information, see sed & awk and the Free Software Foundation book Effective awk Programming, both published by O'Reilly.


Section 11.1. Conceptual Overview

11.1. Conceptual Overview

awk is a pattern-matching program for processing files, especially when each line has a simple field-oriented layout. Linux provides the GNU version of awk, called gawk, which provides a number of additional features. This utility can be invoked either through the standard name awk or through gawk.

Items described here as "common extensions" are available in gawk and most versions of awk offered on other operating systems (often called nawk for "new awk"), but should not be used if strict portability of your programs is important to you.

With gawk, you can:

  • Think of a text file as made up of records and fields in a textual database.

  • Perform arithmetic and string operations.

  • Use programming constructs, such as loops and conditionals.

  • Produce formatted reports.

  • Define your own functions.

  • Execute Unix commands from a script.

  • Process the results of Unix commands.

  • Process command-line arguments gracefully.

  • Work easily with multiple input streams.

  • Flush open output files and pipes.

  • Sort arrays.

  • Retrieve and format system time values.

  • Do bit manipulation.

  • Internationalize your gawk programs, allowing strings to be translated into a local language at runtime.

  • Perform two-way I/O to a coprocess.

  • Open a two-way TCP/IP connection to a socket.

  • Dynamically add built-in functions.

  • Profile your gawk programs.


Section 11.2. Command-Line Syntax

11.2. Command-Line Syntax

The syntax for invoking awk has two forms:

    awk  [options]  'script'  var=value  file(s)
    awk  [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. gawk allows multiple -f scripts. Variables can be assigned a value on the command line. The value can be a string or numeric constant, a shell variable ($name), or a command substitution ('cmd'), but the value is available only after the BEGIN statement is executed.

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

11.2.1. Standard Options

The standard options are:

-Ffs

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

-v var=value

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

For example, to print the first three (colon-separated) fields of each record on separate lines:

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

Numerous examples are shown later in Simple Pattern-Procedure Examples."

11.2.2. Important gawk Options

Besides the standard command line options, gawk has a large number of additional options. This section lists those of most value in day-to-day use. Any unique abbreviation of these options is acceptable.

--dump-variables[=file]

When the program has finished running, print a sorted list of global variables, their types, and their final values to file. The default file is awkvars.out.

--gen-po

Read the awk program and print all strings marked as translatable to standard output in the form of a GNU gettext Portable Object file. See the section Internationalization," later in this chapter, for more information.

--help

Print a usage message to standard error and exit.

--lint[=fatal]

Enable checking of nonportable or dubious constructs, both when the program is read and as it runs. With an argument of fatal, lint warnings become fatal errors.

--non-decimal-data

Allow octal and hexadecimal data in the input to be recognized as such. This option is not recommended; use strtonum( ) in your program, instead.

--profile[=file]

With gawk, put a "prettyprinted" version of the program in file. Default is awkprof.out. With pgawk (see Profiling," later in this chapter), put the profiled listing of the program in file.

--posix

Turn on strict POSIX compatibility, in which all common and gawk-specific extensions are disabled.

--source='program text'

Use program text as the awk source code. Use this option with -f to mix command-line programs with awk library files.

--traditional

Disable all gawk-specific extensions, but allow common extensions (e.g., the ** operator for exponentiation).

--version

Print the version of gawk on standard error and exit.


Section 11.3. Patterns and Procedures

11.3. Patterns and Procedures

awk scripts consist of patterns and procedures:

    pattern  { procedure }

Both pattern and { procedure } are optional. If pattern is missing, { procedure } is applied to all lines. If { procedure } is missing, the matched line is printed.

11.3.1. Patterns

A pattern can be any of the following:

    general expression
    /regular expression/
    relational expression

    pattern-matching expression
    BEGIN
    END

  • General expressions can be composed of quoted strings, numbers, operators, function calls, user-defined variables, or any of the predefined variables described later in this chapter in Built-in Variables."

  • Regular expressions use the extended set of metacharacters, as described in Chapter 7.

  • The ^ and $ metacharacters refer to the beginning and end of a string (such as the fields), respectively, rather than the beginning and end of a line. In particular, these metacharacters will not match at a newline embedded in the middle of a string.

  • Relational expressions use the relational operators listed in the Operators," section, later in this chapter. For example, $2 > $1 selects lines for which the second field is greater than the first. Comparisons can be either string or numeric. Thus, depending upon the types of data in $1 and $2, awk will do either a numeric or a string comparison. This can change from one record to the next.

  • 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 will take place before the first input line is processed. (Generally, you process the command line and set global variables here.)

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

  • BEGIN and END patterns may appear multiple times. The procedures are merged as if there had been one large procedure.

Except for BEGIN and END, patterns can be combined with the Boolean operators || (or), && (and), and ! (not). A range of lines can also be specified using comma-separated patterns:

    pattern,pattern

11.3.2. Procedures

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

  • Variable or array assignments

  • Input/Output commands

  • Built-in functions

  • Control-flow commands

  • User-defined functions

11.3.3. Simple Pattern-Procedure Examples

Print first field of each line:

    { print $1 }

Print all lines that contain pattern:

    /pattern/

Print first field of lines that contain pattern:

    /pattern/ { print $1 }

Select records containing more than two fields:

    NF > 2

Interpret input records as a group of lines up to a blank line. Each line is a single field:

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

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

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

Count and print the number of pattern found:

    /pattern/ { ++x }
    END { print x }

Add numbers in second column and print the total:

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

Print lines that contain less than 20 characters:

    length($0) < 20

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

    NF =  = 7 && /^Name:/

Print the fields of each record in reverse order, one per line:

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


Section 11.4. Built-in Variables

11.4. Built-in Variables

All awk variables are included in gawk.

Version | Variable | Description
awk | ARGC | Number of arguments on the command line.
 | ARGV | An array containing the command-line arguments, indexed from 0 to ARGC - 1.
 | ENVIRON | An associative array of environment variables.
 | FILENAME | Current filename.
 | FNR | Like NR, but relative to the current file.
 | FS | Field separator (a space).
 | NF | Number of fields in current record.
 | NR | Number of the current record.
 | OFMT | Output format for numbers ("%.6g").
 | OFS | Output field separator (a space).
 | ORS | Output record separator (a newline).
 | RLENGTH | Length of the string matched by match( ) function.
 | RS | Record separator (a newline).
 | RSTART | First position in the string matched by match( ) function.
 | SUBSEP | Separator character for array subscripts ("\034").
 | $0 | Entire input record.
 | $n | nth field in current record; fields are separated by FS.
gawk | ARGIND | Index in ARGV of current input file.
 | BINMODE | Controls binary I/O for input and output files. Use values of 1, 2, or 3 for input, output, or both kinds of files, respectively. Set it on the command line to affect standard input, standard output, and standard error.
 | ERRNO | A string indicating the error when a redirection fails for getline or if close( ) fails.
 | FIELDWIDTHS | A space-separated list of field widths to use for splitting up the record, instead of FS.
 | IGNORECASE | When true, all regular expression matches, string comparisons, and index( ) ignore case.
 | LINT | Dynamically controls production of "lint" warnings. With a value of "fatal", lint warnings become fatal errors.
 | PROCINFO | An array containing information about the process, such as real and effective UID numbers, process ID number, and so on.
 | RT | The text matched by RS, which can be a regular expression in gawk.
 | TEXTDOMAIN | The text domain (application name) for internationalized messages ("messages").


Section 11.5. Operators

11.5. Operators

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

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

NOTE

While ** and **= are common extensions, they are not part of POSIX awk.


Section 11.6. Variable and Array Assignment

11.6. Variable and Array Assignment

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

    FS = ","

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

Arrays can be created with the split( ) function (described later), or they can simply be named in an assignment statement. Array elements can be subscripted with numbers (array[1], ..., array[n]) or with strings. Arrays subscripted by strings are called associative arrays.[*] For example, to count the number of widgets you have, you could use the following script:

[*] In fact, all arrays in awk are associative; numeric subscripts are converted to strings before being used as array subscripts. Associative arrays are one of awk's most powerful features.

    /widget/ { count["widget"]++ }       Count widgets
    END      { print count["widget"] }   Print the count

You can use the special for loop to read all the elements of an associative array:

    for (item in array)
            process array[item]

The index of the array is available as item, while the value of an element of the array can be referenced as array[item].

You can use the operator in to test that an element exists by testing to see if its index exists. For example:

    if (index in array)
            ...

tests that array[index] exists, but you cannot use it to test the value of the element referenced by array[index].

You can also delete individual elements of the array using the delete statement. (See also the delete entry in Alphabetical Summary of awk Functions and Commands," later in this chapter.)

11.6.1. Escape sequences

Within string and regular-expression constants, the following escape sequences may be used.

Sequence | Meaning | Sequence | Meaning
\a | Alert (bell) | \v | Vertical tab
\b | Backspace | \\ | Literal backslash
\f | Form feed | \nnn | Octal value nnn
\n | Newline | \xnn | Hexadecimal value nn
\r | Carriage return | \" | Literal double quote (in strings)
\t | Tab | \/ | Literal slash (in regular expressions)

NOTE

The \x escape sequence is a common extension; it is not part of POSIX awk.

11.6.2. Octal and Hexadecimal Constants in gawk

gawk allows you to use octal and hexadecimal constants in your program source code. The form is as in C: octal constants start with a leading 0, and hexadecimal constants with a leading 0x or 0X. The hexadecimal digits a-f may be in either uppercase or lowercase.

    $ gawk 'BEGIN { print 042, 42, 0x42 }'
    34 42 66

Use the strtonum( ) function to convert octal or hexadecimal input data into numerical values.


Section 11.7. User-Defined Functions

11.7. User-Defined Functions

gawk allows you to define your own functions. This makes it easy to encapsulate sequences of steps that need to be repeated into a single place and reuse the code from anywhere in your program.

The following function capitalizes each word in a string. It has one parameter, named input, and five local variables, which are written as extra parameters:

    # capitalize each word in a string
    function capitalize(input, result, words, n, i, w)
    {
       result = ""
       n = split(input, words, " ")
       for (i = 1; i <= n; i++) {
            w = words[i]
            w = toupper(substr(w, 1, 1)) substr(w, 2)
            if (i > 1)
                     result = result " "
            result = result w
       }
       return result
    }

    # main program, for testing
    { print capitalize($0) }

With this input data:

    A test line with words and numbers like 12 on it.

This program produces:

    A Test Line With Words And Numbers Like 12 On It.

NOTE

For user-defined functions, no space is allowed between the function name and the left parenthesis when the function is called.


Section 11.8. Gawk-specific Features

11.8. Gawk-specific Features

This section describes features unique to gawk.

11.8.1. Coprocesses and Sockets

gawk allows you to open a two-way pipe to another process, called a coprocess. This is done with the |& operator used with getline and print or printf.

    print database command |& "db_server"
    "db_server" |& getline response

If the command used with |& is a filename beginning with /inet/, gawk opens a TCP/IP connection. The filename should be of the following form:

    /inet/protocol/lport/hostname/rport

The parts of the filename are:

protocol

One of tcp, udp or raw, for TCP, UDP, or raw IP sockets, respectively. Note: raw is currently reserved but unsupported.

lport

The local TCP or UPD port number to use. Use 0 to let the operating system pick a port.

hostname

The name or IP address of the remote host to connect to.

rport

The port (application) on the remote host to connect to. A service name (e.g., tftp) is looked up using the C getservbyname( ) function.

11.8.2. Profiling

When gawk is built and installed, a separate program named pgawk (profiling gawk) is built and installed with it. The two programs behave identically; however, pgawk runs more slowly because it keeps execution counts for each statement as it runs. When it is done, it automatically places an execution profile of your program in a file named awkprof.out. (You can change the filename with the --profile option.)

The execution profile is a "prettyprinted" version of your program, with execution counts listed in the left margin. For example, after running this program:

    $ pgawk '/bash$/ { nusers++ }
    > END { print nusers, "users use Bash." }' /etc/passwd
    16 users use Bash.

the execution profile looks like this:

        # gawk profile, created Mon Nov  1 14:34:38 2004

        # Rule(s)

    35  /bash$/ { # 16
    16          nusers++
        }

        # END block(s)

        END {
     1          print nusers, "users use Bash."
        }

If sent SIGUSR1, pgawk prints the profile and an awk function call stack trace, and then keeps going. Multiple SIGUSR1 signals may be sent; the profile and trace will be printed each time. This facility is useful if your awk program appears to be looping and you want to see if something unexpected is being executed.

If sent SIGHUP, pgawk prints the profile and stack trace, and then exits.

11.8.3. File Inclusion

The igawk program provides a file-inclusion facility for gawk. You invoke it the same way you do gawk: it passes all command line arguments on to gawk. However, igawk processes source files and command-line programs for special statements of the form:

    @include file.awk

Such files are searched for along the list of directories specified by the AWKPATH environment variable. When found, the @include line is replaced with the text of the corresponding file. Included files may themselves include other files with @include.

The combination of the AWKPATH environment variable and igawk makes it easy to have and use libraries of awk functions.

11.8.4. Internationalization

You can internationalize your programs if you use gawk. This consists of choosing a text domain for your program, marking strings that are to be translated, and, if necessary, using the bindtextdomain( ), dcgettext( ), and dcngettext( ) functions.

Localizing your program consists of extracting the marked strings, creating translations, and compiling and installing the translations in the proper place. Full details are given in Effective awk Programming (O'Reilly).

The internationalization features in gawk use GNU gettext. You may need to install the GNU gettext tools to create translations if your system doesn't already have them. Here is a very brief outline of the steps involved:

  1. Set TEXTDOMAIN to your text domain in a BEGIN block:

        BEGIN { TEXTDOMAIN = "whizprog" }

  2. Mark all strings to be translated by prepending a leading underscore:

        printf(_"whizprog: can't open /dev/telepath (%s)\n",
                       dcgettext(ERRNO)) > "/dev/stderr"

  3. Extract the strings with the --gen-po option:

        $ gawk --gen-po -f whizprog.awk > whizprog.pot

  4. Copy the file for translating, and make the translations:

        $ cp whizprog.pot esperanto.po
    $ ed esperanto.po

  5. Use the msgfmt program from GNU gettext to compile the translations. The binary format allows fast lookup of the translations at runtime. The default output is a file named messages:

        $ msgfmt esperanto.po
    $ mv messages esperanto.mo

  6. Install the file in the standard location. This is usually done at program installation. The location can vary from system to system.

That's it! gawk will automatically find and use the translated messages, if they exist.


Section 11.9. Implementation Limits

11.9. Implementation Limits

Many versions of awk have various implementation limits, on things such as:

  • Number of fields per record

  • Number of characters per input record

  • Number of characters per output record

  • Number of characters per field

  • Number of characters per printf string

  • Number of characters in literal string

  • Number of characters in character class

  • Number of files open

  • Number of pipes open

  • The ability to handle 8-bit characters and characters that are all zero (ASCII NUL)

gawk does not have limits on any of the above items, other than those imposed by the machine architecture and/or the operating system.


Section 11.10. Group Listing of awk Functions and Commands

11.10. Group Listing of awk Functions and Commands

The following table classifies awk functions and commands.

Function type |  |  | Functions or commands |  |
Arithmetic | atan2 | cos | exp | int | log
 | rand | sin | sqrt | srand |
String | asort[a] | asorti[a] | gensub[a] | gsub | index
 | length | match | split | sprintf | strtonum[a]
 | sub | substr | tolower | toupper |
Control flow | break | continue | do/while | exit | for
 | if/else | return | while |  |
I/O | close | fflush[b] | getline | next | nextfile[b]
 | print | printf |  |  |
Programming | extension[a] | delete | function | system |

[a] Available in gawk.

[b] Available in Bell Labs awk and gawk.

The following functions are specific to gawk.

Function type |  |  | Functions or commands |  |
Bit manipulation | and | compl | lshift | or | rshift
 | xor |  |  |  |
Time | mktime | strftime | systime |  |
Translation | bindtextdomain | dcgettext | dcngettext |  |


Section 11.11. Alphabetical Summary of awk Functions and Commands

11.11. Alphabetical Summary of awk Functions and Commands

The following alphabetical list of keywords and functions includes all that are available in POSIX awk and gawk. Extensions that aren't part of POSIX awk but that are in both gawk and the Bell Laboratories awk are marked as {E}. Cases where gawk has extensions are marked as {G}. Items that aren't marked with a symbol are available in all versions.

#
    #

Ignore all text that follows on the same line. # is used in awk scripts as the comment character and is not really a command.

and
    and(expr1, expr2) {G}

Return the bitwise AND of expr1 and expr2, which should be values that fit in a C unsigned long.

asort
    asort(src [,dest]) {G}

Sort the array src based on the element values, destructively replacing the indices with values from one to the number of elements in the array. If dest is supplied, copy src to dest and sort dest, leaving src unchanged. Returns the number of elements in src.

asorti
    asorti(src [,dest]) {G}

Like asort( ), but the sorting is done based on the indices in the array, not based on the element values. For gawk 3.1.2 and later.

atan2
    atan2(y, x)

Return the arctangent of y/x in radians.

bindtextdomain
    bindtextdomain(dir [,domain]) {G}

Look in directory dir for message translation files for text domain domain (default: value of TEXTDOMAIN). Returns the directory where domain is bound.

break
    break

Exit from a while, for, or do loop.

close
    close(expr)
    close(expr, how) {G}

In most implementations of awk, you can only have up to ten files and one pipe open simultaneously. Therefore, POSIX awk provides a close( ) function that allows you to close a file or a pipe. It takes the same expression that opened the pipe or file as an argument. This expression must be identical, character by character, to the one that opened the file or pipeeven whitespace is significant.

In the second form, close one end of either a TCP/IP socket or a two-way pipe to a coprocess. how is a string, either "from" or "to". Case does not matter.

compl
    compl(expr) {G}

Return the bitwise complement of expr, which should be a value that fits in a C unsigned long.

continue
    continue

Begin next iteration of while, for, or do loop.

cos
    cos(x)

Return the cosine of x, an angle in radians.

dcgettext
    dcgettext(str [, dom [,cat]]) {G}

Return the translation of str for the text domain dom in message category cat. Default text domain is value of TEXTDOMAIN. Default category is "LC_MESSAGES".

dcngettext
    dcngettext(str1, str2, num [, dom [,cat]]) {G}

If num is one, return the translation of str1 for the text domain dom in message category cat. Otherwise, return the translation of str2. Default text domain is value of TEXTDOMAIN. Default category is "LC_MESSAGES". For gawk 3.1.1 and later.

delete
    delete array[element]
    delete array {E}

Delete element from array. The brackets are typed literally. The second form is a common extension, which deletes all elements of the array in one shot.

do
    do
     statement
    while (expr)

Looping statement. Execute statement, then evaluate expr and if true, execute statement again. A series of statements must be put within braces.

exit
    exit [expr]

Exit from script, reading no new input. The END procedure, if it exists, will be executed. An optional expr becomes awk's return value.

exp
    exp(x)

Return exponential of x (ex).

extension
    extension(lib, init) {G}

Dynamically load the shared object file lib, calling the function init to initialize it. Return the value returned by the init function. This function allows you to add new built-in functions to gawk. See Effective awk Programming (O'Reilly) for the details.

fflush
    fflush([output-expr]) {E}

Flush any buffers associated with open output file or pipe output-expr.

gawk extends this function. If no output-expr is supplied, it flushes standard output. If output-expr is the null string (""), it flushes all open files and pipes.

for
    for (init-expr; test-expr; incr-expr)
     statement

C-style looping construct. init-expr assigns the initial value of a counter variable. test-expr is a relational expression that is evaluated each time before executing the statement. When test-expr is false, the loop is exited. incr-expr is used to increment the counter variable after each pass. All of the expressions are optional. A missing test-expr is considered to be true. A series of statements must be put within braces.

for
    for (item in array)
     statement

Special loop designed for reading associative arrays. For each element of the array, the statement is executed; the element can be referenced by array [item]. A series of statements must be put within braces.

function
    function name(parameter-list) {
     statements
    }

Create name as a user-defined function consisting of awk statements that apply to the specified list of parameters. No space is allowed between name and the left parenthesis when the function is called.

gensub
    gensub(regex, str, how [, target]) {G}

General substitution function. Substitute str for matches of the regular expression regex in the string target. If how is a number, replace the howth match. If it is "g" or "G", substitute globally. If target is not supplied, $0 is used. Return the new string value. The original target is not modified. (Compare with gsub and sub.) Use & in the replacement string to stand for the text matched by the pattern.

getline
    getline
    getline [var] [< file]
    command | getline [var]
    command |& getline [var] {G}

Read next line of input.

The second form reads input from file, and the third form reads the output of command. All forms read one record at a time, and each time the statement is executed, it gets the next record of input. The record 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 $0 and NF are not changed. Thus, if the result is assigned to a variable, the current record does not change. getline is actually a function, and it returns 1 if it reads a record successfully, 0 if end-of-file is encountered, and -1 if for some reason it is otherwise unsuccessful.

The fourth form reads the output from coprocess command. See the section Coprocesses and Sockets," for more information.

gsub
    gsub(regex, str [, target])

Globally substitute str for each match of the regular expression regex in the string target. If target is not supplied, defaults to $0. Return the number of substitutions. Use & in the replacement string to stand for the text matched by the pattern.

if
    if (condition)
     statement1
    [else
     statement2]

If condition is true, do statement1; otherwise do statement2 in optional else clause. The condition can be an expression using any of the relational operators <, <=, = =, !=, >=, or >, as well as the array membership operator in, and the pattern-matching operators ~ and !~ (e.g., if ($1 ~ /[Aa].*/)). A series of statements must be put within braces. Another if can directly follow an else in order to produce a chain of tests or decisions.

index
    index(str, substr)

Return the position (starting at 1) of substr in str, or zero if substr is not present in str.

int
    int(x)

Return integer value of x by truncating any fractional part.

length
    length([arg])

Return length of arg, or the length of $0 if no argument.

log
    log(x)

Return the natural logarithm (base e) of x.

lshift
    lshift(expr, count) {G}

Return the result of shifting expr left by count bits. Both expr and count should be values that fit in a C unsigned long.

match
    match(str, regex)
    match(str, regex [, array]) {G}

Function that matches the pattern, specified by the regular expression regex, in the string str and returns either the position in str where the match begins, or 0 if no occurrences are found. Sets the values of RSTART and RLENGTH to the start and length of the match, respectively.

If array is provided, gawk puts the text that matched the entire regular expression in array[0], the text that matched the first parenthesized subexpression in array[1], the second in array[2], and so on.

mktime
    mktime(timespec) {G}

Turns timespec (a string of the form YYYY MM DD HH MM SS[DST] representing a local time) into a time-of-day value in seconds since midnight, January 1, 1970, UTC.

next
    next

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

nextfile
    nextfile {E}

Stop processing the current input file and start new cycle through pattern/procedures statements, beginning with the first record of the next file.

or
    or(expr1, expr2) {G}

Return the bitwise OR of expr1 and expr2, which should be values that fit in a C unsigned long.

print
    print [ output-expr[ , ...]] [ dest-expr ]

Evaluate the output-expr and direct it to standard output followed by the value of ORS. Each comma-separated output-expr is separated in the output by the value of OFS. With no output-expr, print $0. The output may be redirected to a file or pipe via the dest-expr, which is described in Output Redirections," later in this chapter.

printf
    printf(format [, expr-list ]) [ dest-expr ]

An alternative output statement borrowed from the C language. It has the ability to produce formatted output. It can also be used to output data without automatically producing a newline. format is a string of format specifications and constants. expr-list is a list of arguments corresponding to format specifiers. As for print, output may be redirected to a file or pipe. See printf Formats," later in this chapter, for a description of allowed format specifiers.

Like any string, format can also contain embedded escape sequences: \n (newline) or \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, there should be multiple formats specified.

Examples

Using the script:

    { printf("The sum on line %d is %.0f.\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 srand( ).

return
    return [expr]

Used within a user-defined function to exit the function, returning the value of expr. The return value of a function is undefined if expr is not provided.

rshift
    rshift(expr, count) {G}

Return the result of shifting expr right by count bits. Both expr and count should be values that fit in a C unsigned long.

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]. Return the number of array elements created. The string is split at each occurrence of separator sep. If sep is not specified, FS is used.

sprintf
    sprintf(format [, expressions])

Return the formatted value of one or more expressions, using the specified format. Data is formatted but not printed. See printf Formats," later in this chapter, for a description of allowed format specifiers.

sqrt
    sqrt(arg)

Return the square root of arg.

srand
    srand([expr])

Use optional expr to set a new seed for the random number generator. Default is the time of day. Return value is the old seed.

strftime
    strftime([format [,timestamp]]) {G}

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. 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 the Unix date command. See the date entry in Chapter 3 for a list.

strtonum
    strtonum(expr) {G}

Return the numeric value of expr, which is a string representing an octal, decimal, or hexadecimal number in the usual C notations. Use this function for processing nondecimal input data.

sub
    sub(regex, str [, target])

Substitute str for first match of the regular expression regex in the string target. If target is not supplied, defaults to $0. Returns 1 if successful, 0 otherwise. Use & in the replacement string to stand for the text matched by the pattern.

substr
    substr(string, beg [, len])

Return substring of string at beginning position beg (counting from 1), and the characters that follow to maximum specified length len. If no length is given, use the rest of the string.

system
    system(command)

Function that executes the specified command and returns its exit status. The status of the executed command typically indicates success or failure. A value of 0 means that the command executed successfully. A nonzero value indicates a failure of some sort. The documentation for the command you're running will give you the details.

awk does not make the output of the command available for processing within the awk script. Use command | getline to read the output of a command into the script.

systime
    systime(  ) {G}

Return a time-of-day value in seconds since midnight, January 1, 1970, UTC.

Examples

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.[*]

[*] Very early versions of nawk don't support tolower( ) and toupper( ). However, they are now part of the POSIX specification for awk.

toupper
    toupper(str)

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

while
    while (condition)
     statement

Do statement while condition is true (see if for a description of allowable conditions). A series of statements must be put within braces.

xor
    xor(expr1, expr2) {G}

Return the bitwise XOR of expr1 and expr2, which should be values that fit in a C unsigned long.

11.12.1. Output Redirections

For print and printf, dest-expr is an optional expression that directs the output to a file or pipe.

> file

Direct the output to a file, overwriting its previous contents.

>> file

Append the output to a file, preserving its previous contents. In both this case and the > file case, the file will be created if it does not already exist.

| command

Direct the output as the input to a system command.

|& command

Direct the output as the input to a coprocess. gawk only.

Be careful not to mix > and >> for the same file. Once a file has been opened with >, subsequent output statements continue to append to the file until it is closed.

Remember to call close( ) when you have finished with a file, pipe, or coprocess. If you don't, eventually you will hit the system limit on the number of simultaneously open files.

11.12.2. printf Formats

Format specifiers for printf and sprintf have the following form:

    %[posn$][flag][width][.precision]letter

The control letter is required. The format-conversion control letters are given in the following table.

Character | Description
c | ASCII character.
d | Decimal integer.
i | Decimal integer. (Added in POSIX)
e | Floating-point format ([-]d.precisione[+-]dd).
E | Floating-point format ([-]d.precisionE[+-]dd).
f | Floating-point format ([-]ddd.precision).
g | e or f conversion, whichever is shortest, with trailing zeros removed.
G | E or f conversion, whichever is shortest, with trailing zeros removed.
o | Unsigned octal value.
s | String.
u | Unsigned decimal value.
x | Unsigned hexadecimal number. Uses a-f for 10 to 15.
X | Unsigned hexadecimal number. Uses A-F for 10 to 15.
% | Literal %.

gawk allows you to provide a positional specifier after the % (posn$). A positional specifier is an integer count followed by a $. The count indicates which argument to use at that point. Counts start at one and don't include the format string. This feature is primarily for use in producing translations of format strings. For example:

    $ gawk 'BEGIN { printf "%2$s, %1$s\n", "world", "hello" }'
    hello, world

The optional flag is one of the following:

Character | Description
- | Left-justify the formatted value within the field.
space | Prefix positive values with a space and negative values with a minus.
+ | Always prefix numeric values with a sign, even if the value is positive.
# | Use an alternate form: %o has a preceding 0; %x and %X are prefixed with 0x and 0X, respectively; %e, %E and %f always have a decimal point in the result; and %g and %G do not have trailing zeros removed.
0 | Pad output with zeros, not spaces. This only happens when the field width is wider than the converted result. This flag applies to all output formats, even nonnumeric ones.
' | gawk 3.1.4 and later only. For numeric formats, in locales that support it, supply a thousands-separator charater.

The optional width is the minimum number of characters to output. The result will be padded to this size if it is smaller. The 0 flag causes padding with zeros; otherwise, padding is with spaces.

The precision is optional. Its meaning varies by control letter, as shown in the following table:

Conversion | Precision means
%d, %i, %o, %u, %x, %X | The minimum number of digits to print.
%e, %E, %f | The number of digits to the right of the decimal point.
%g, %G | The maximum number of significant digits.
%s | The maximum number of characters to print.


Section 11.13. Source Code

11.13. Source Code

The following URLs indicate where to get source code for four freely available versions of awk and GNU gettext.

http://cm.bell-labs.com/~bwk

Brian Kernighan's home page, with links to the source code for the latest version of awk from Bell Laboratories.

ftp://ftp.whidbey.net/pub/brennan/mawk1.3.3.tar.gz

Michael Brennan's mawk. A very fast, very robust version of awk.

ftp://ftp.gnu.org/gnu/gawk/

The Free Software Foundation's version of awk, called gawk.

http://www.gnu.org/software/gawk/gawk.html

The Free Software Foundation's home page for gawk.

http://awka.sourceforge.net

The home page for awka, a translator that turns awk programs into C, compiles the generated C, and then links the object code with a library that performs the core awk functions.

ftp://ftp.gnu.org/gnu/gettext/

The source code for GNU gettext. Get this if you need to produce translations for your awk programs that use gawk.


Chapter 12. Source Code Management: An Overview

Chapters 13 and 14 describe two popular source code management systems for Linux: CVS and Subversion (SVN). This chapter introduces the major concepts involved with using these systems for users who may never have used one. If you're already familiar with source code management, feel free to skip ahead to the particular software suite that interests you. See also the O'Reilly books Essential CVS, CVS Pocket Reference, and Version Control with Subversion.

This chapter covers the following topics:

  • Introduction and terminology

  • Usage models

  • Source code management systems

  • Other source code management systems


Section 12.1. Introduction and Terminology

12.1. Introduction and Terminology

Source code management systems let you store and retrieve multiple versions of a file. While originally designed for program source code, they can be used for any kind of file: source code, documentation, configuration files, and so on. Modern systems allow you to store binary files as well, such as image or audio data.

Source code management systems let you compare different versions of a file, as well as do "parallel development." In other words, you can work on two different versions of a file at the same time, with the source code management system storing both versions. You can then merge changes from two versions into a third version. This will become more clear shortly. We'll start by defining some terms.

Repository

A repository is where the source code management system stores its copy of your file. Usually one file in the source code management system is used to hold all the different versions of a source file. Each source code management system uses its own format to allow it to retrieve different versions easily and to track who made what changes, and when.

Sandbox

A sandbox is your personal, so-called "working copy" of the program or set of documents under development. You edit your private copy of the file in your own sandbox, returning changes to the source code management system when you're satisfied with the new version.

Check in, check out

You "check out" files from the repository, edit them, and then "check them in" when you're satisfied with your changes. Other developers working against the same repository will not see your changes until after you check them back in. Another term used for check-in is commit.

Log message

Every time you check in a file, you are prompted for a message describing the changes you made. You should do so in a concise fashion. If your software development practices include the use of a bug tracking system, you might also wish to include the bug number or problem report (PR) number that your change resolves.

Keyword substitutions

When you check out a file, the source code management system can replace special keywords with values representing such things as the file's version number, the name of the user who made the most recent change, the date and time the file was last changed, the file's name, and so on. Each of the systems described in this book uses an overlapping set of keywords. Some systems always do keyword substitution, while others require that you explicitly enable the feature for each file.

Branch

A branch is a separate development path. For example, once you've released version 1.0 of whizprog, you will wish to proceed with the development for version 2.0. The main line of development is often called the trunk.

Now consider what happens when you wish to make a bug-fix release to whizprog 1.0, to be named version 1.1. You create a separate branch, based on the original 1.0 code, in a new sandbox. You perform all your development there, without disturbing the development being done for the 2.0 release.

Tag

A tag is a name you give to a whole group of files at once, at whatever version each individual file may be, in order to identify those files as being part of a particular group. For example, you might create tags WHIZPROG-1_0-ALPHA, WHIZPROG-1_0-BETA, WHIZPROG-1_0-RELEASE and so on. This is a powerful facility that should be used well, since it allows you to retrieve a "snapshot" of your entire development tree as it existed at different points in time.

Merging

Most typically, when development along a branch is completed, it becomes necessary to merge the changes from that branch back into the main line of development. In our hypothetical example, all the bugs fixed in whizprog 1.0 to create version 1.1 should also be fixed in the ongoing 2.0 development. Source code management systems can help you automate the process of merging.

Conflict

A conflict occurs when two developers make inconsistent changes to the same part of a source file. Modern source code management systems detect the conflict, usually marking the conflicting parts of the file in your working copy using special markers. You first discuss the conflict with the other developer, in order to arrive at a correct resolution of the conflict. Once that's done, you then resolve the conflict manually (by making the appropriate changes) and check in the new version of the file.

Client/Server

As with other "client/server" networking models, the idea here is that the repository is stored on one machine, the server, and that different developers may access the repository from multiple client systems. This powerful feature facilitates distributed development, allowing developers to work easily on their local systems, with the repository kept in a central place where it can be easily accessed and administered.


Section 12.2. Usage Models

12.2. Usage Models

Different systems have different conceptual "models" as to how they're used.

Older systems such as SCCS and RCS use a "check out with locking" model. These systems were developed before client/server computing, when software development was done on centralized minicomputers and mainframes. In this model, the repository is a central directory on the same machine where the developers work, and each developer checks out a private copy into their own sandbox. In order to avoid two developer's making conflicting changes to a file, the file must be locked when it's checked out. Only one user may lock a particular version of a file at a time. When that user has checked in their changes, they unlock the file so that the next user can check in changes. If necessary, the second user may "break" the first user's lock, in which case the first user is notified via electronic mail.

This model works well for small projects where developers are co-located and can communicate easily. As long as one developer locks a file when she checks it out, another developer wishing to work with the file will know that he can't until the first one is done. The drawback is that such locking can slow down development significantly.

Newer systems, such as CVS and Subversion, use an "copy, modify, merge" model. In practice, when two developers wish to work on the same file, they usually end up changing different, unrelated parts of the file. Most of the time, each developer can make changes without adversely affecting the other. Thus, files are not locked upon checkout into a sandbox. Instead, the source code management system detects conflicts and disallows a check-in when conflicts exist.

For example, consider two developers, dangermouse and penfold, who are both working on whizprog.c. They each start with version 1.4 of the file. dangermouse commits his changes, creating version 1.5. Before penfold can commit his changes, the source code management system notices that the file has changed in the repository. penfold must first merge dangermouse's changes into his working copy. If there are no conflicts, he can then commit his changes, creating version 1.6. On the other hand, if there are conflicts, he must first resolve them (they'll be marked in the working copy), and only then may he commit his version.

The combination of the "copy, modify, merge" model with a networked client/server facility creates a powerful environment for doing distributed development. Developers no longer have to worry about file locks. Because the source code management system enforces serialization (making sure that new changes are based on the latest version in the repository), development can move more smoothly, with little danger of miscommunication or that successive changes will be lost.


Section 12.3. Source Code Management Systems

12.3. Source Code Management Systems

There are several source code management systems used in the Unix community:

SCCS

The Source Code Control System. SCCS is the original Unix source code management system. It was developed in the late 1970s for the Programmer's Workbench (PWB) Unix systems within Bell Labs. It is still in use at a few large longtime Unix sites. However, for a long time it was not available as a standard part of most commercial or BSD Unix systems, and it did not achieve the widespread popularity of other, later systems. (It is still available with Solaris.) SCCS uses a file storage format that allows it to retrieve any version of a source file in constant time.

RCS

The Revision Control System. RCS was developed in the early 1980s at Purdue University by Walter F. Tichy. It became popular in the Unix world when it was shipped with 4.2 BSD in 1983. At the time, Berkeley Unix was the most widely used Unix variant, even though to get it, a site had to have a Unix license from AT&T.

RCS is easier to use than SCCS. Although it has a number of related commands, only three or four are needed for day-to-day use, and they are quickly mastered. A central repository is easy to use: you first create a directory for the sandbox. In the sandbox, you make a symbolic link to the repository named RCS, and then all the developers can share the repository. RCS uses a file format that is optimized for retrieving the most recent version of a file.

CVS

The Concurrent Versions System. CVS was initially built as a series of shell scripts sitting atop RCS. Later it was rewritten in C for robustness, although still using RCS commands to manage the storage of files. However, for quite some time, CVS has had the RCS functionality built into it, and it no longer requires that RCS be available. The file format continues to be the same. CVS was the first distributed source code management system and is currently the standard one for Unix systemsin particular for collaborative, distributed, Free and open source development projects.

The repository is named when you create a sandbox and is then stored in the files in the sandbox, so that it need not be provided every time you run a CVS command. Unlike SCCS and RCS, which provide multiple commands, CVS has one main command (named cvs), which you use for just about every operation.

Subversion

With increasing use, it became clear that CVS lacked some fundamental capabilities. The Subversion project was started by several longtime CVS users and developers with the explicit goal to "build a better CVS," not necessarily to explore uncharted territory in source code management systems. Subversion is thus intentionally easy to learn for CVS users. Subversion uses its own format for data storage, based on the Berkeley DB in-process data library. Distributed use was designed in from day one, providing useful facilities that leverage the capabilities of the well-known Apache HTTP server.

RCS, CVS, and Subversion represent a progression, each one building on the features of its predecessors. For example, all three share a large subset of the same keyword substitutions, and command names are similar or identical in all three. They also demonstrate the progression from centralized, locking-based development to distributed, conflict-resolution-based development.


Section 12.4. Other Source Code Management Systems

12.4. Other Source Code Management Systems

Besides the source code management systems covered in this book, several other systems are worth knowing about. The following list, though, is by no means exhaustive:

Arch

GNU Arch is a distributed source code management system similar to CVS and Subversion. One of its significant strengths is that you can do offline development with it, working on multiple versions even on systems that are not connected to the Internet and that cannot communicate with the central repository. For more information, see http://www.gnu.org/software/gnu-arch/.

Codeville

Codeville is a distributed version-control system in the early stages of development. It is written in Python, is easy to set up and use, and shows a lot of promise. For more information, see http://codeville.org/.

CSSC

CSSC is a free clone of SCCS. It intends to provide full compatibility with SCCS, including file format, command names and options, and "bug for bug" compatible behavior. If you have an existing SCCS repository, you should be able to drop CSSC into your environment, in place of SCCS. CSSC can be used to migrate from a commercial Unix system to a freely available clone, such as GNU/Linux or a BSD system. For more information, see http://directory.fsf.org/GNU/CSSC.html.

Monotone

The web page for monotone describes it well:

monotone is a free distributed version control system. It provides a simple, single-file transactional version store, with fully disconnected operation and an efficient peer-to-peer synchronization protocol. It understands history-sensitive merging, lightweight branches, integrated code review, and third party testing. It uses cryptographic version naming and client-side RSA certificates. It has good internationalization support, has no external dependencies, runs on [Linux, Solaris, Mac OS X, NetBSD, and Windows], and is licensed under the GNU GPL.

For more information, see http://www.venge.net/monotone/.


Chapter 13. The Concurrent Versions System (CVS)

This chapter is a comprehensive reference of all CVS commands, with a brief summary of what each does. It is intended to be useful as a quick reference, not a tutorial.

This chapter covers the following topics:

  • Conceptual overview

  • Command-line syntax and options

  • CVS dot files

  • Environment variables

  • Keywords and keyword modes

  • Dates

  • CVSROOT variables

  • Alphabetical summary of commands

Most of the material in this chapter is adapted from the O'Reilly book Essential CVS. The Internet starting point for CVS is http://www.cvshome.org/.


Conceptual Overview

The basic concepts for source code management systems were presented in Chapter 12. As described there, CVS is a distributed source code management system based on the "copy, modify, merge" model. It uses RCS format files for storing data in its repository and is currently the most popular source code management suite for Unix and Unix-like systems.

Table 13-1 is a quick-start guide to using CVS. You can use the commands in the order shown to create and start using a CVS repository. (The basic steps for using CVS are similar to those for the Subversion source code management system, described in detail in Chapter 14.)

Table 13-1. CVS commands quick start guide

Command

Purpose

mkdir /path/to/repos

Make the repository directory.

cvs init /path/to/repos

Initialize the repository.

cvs import ...

Import the initial version of a project into the repository.

cvs checkout ...

Create a sandbox.

cvs diff ...

Compare the sandbox to the repository, or different versions in the repository.

cvs status

Check if files have changed in the sandbox or the repository.

cvs update

Download changes from the repository to the sandbox.

cvs commit

Upload changes from the sandbox to the repository.

CVS Wrappers

When resolving conflicts, the usual method CVS uses is MERGE, which means that CVS puts both versions of the conflicting group of lines into the file, surrounded by special markers. However, this method doesn't work for binary files. Thus, the second conflict-resolution method is COPY, which presents both versions of the file to the user for manual resolution.

You can manually specify the conflict resolution method and keyword expansion method when a file is added to a repository, as well as later, after the file is already there. However, doing so manually for lots of files is painful and error-prone. Wrappers allow you to specify the conflict resolution method and keyword expansion method for groups of files, based on filename patterns. You may do this on the command line or, more conveniently, by placing the wrappers into a .cvswrappers file. Each line has the following format:

        wildcard
option
'value'
[option
'value'...]

The wildcard is a shell-style wildcard pattern. If option is -m, it indicates the conflict resolution method. In this case, value should be either MERGE or COPY. If option is -k, then value is one of the keyword resolution modes (b, k, o, etc.).

Stickiness

When some aspect of the persistent state of a file in a sandbox is different from that of the file in the repository, that aspect is said to be sticky. For example, when a file is retrieved based on a specific date, tag, or revision, those attributes are sticky. Similarly, when a file in a sandbox belongs to a branch, the branch is said to be sticky, and if the keyword expansion mode is set on a file, that mode is also sticky. Entire directories may be marked as sticky, not just individual files.

These attributes are termed "sticky" because the state of the file becomes persistent. In particular, a cvs update does not update such files to the latest revision in the repository. Similarly, you cannot use cvs commit to make such a file become the head of a branch or the trunk in the repository. Finally, when a file is on a sticky branch, it can only be committed on that branch. cvs status shows the stickiness of various attributes.

This all makes sense: work on a branch should be done only on that branch. When work on the branch is finished, the branch's changes should be merged into the files on the trunk, instead of checking the files into the head of the trunk directly.

Stickiness is created or changed using the -D, -k or -r options to cvs checkout and cvs update. Use cvs update -A to remove stickiness. You must use this command on a sticky directory directly; applying it just to all the contained files in the directory is not enough.

See Chapter 4 in Essential CVS (O'Reilly) for more details.


Command-Line Syntax and Options

CVS supports a number of command-line options that you can use to control various aspects of CVS behavior. Each CVS subcommand has its own options, as well.

The syntax of any CVS command is as follows:

        cvs
[cvs-options]
[command]
[command-options-and-arguments]

The cvs-options modify the behavior of the main CVS code, rather than the code for a specific command.

cvs Options

Options to the cvs command are supplied before the particular subcommand to be executed. This section focuses on options that you pass to the cvs executable itself, not to any specific CVS command. The following options are valid:

-a

Authenticate all network traffic. Without this option, the initial connection for the command is authenticated, but later traffic along the same data stream is assumed to be from the same source.

This option is available only with GSS-API connections, but if you use ssh as your rsh replacement in the ext connection mode, ssh authenticates the data stream.

This option is supported if it is listed in cvs --help-options. The command-line client can be compiled to support it by using the --enable-client option to the configure script.

-allow-root=directory

Used as part of the inetd command string for the server, kserver, and pserver connection methods. The directory is the repository root directory to which the server allows connections. Using --allow-root more than once in a command allows users to connect to any of the specified repositories.

d repository_path

Use repository_path as the path to the repository root directory. This option overrides both the CVSROOT environment variable and the contents of the Root file in the sandbox's CVS subdirectory. It also overrides the contents of the .cvsrc file.

The syntax for the repository path is:

[:method:][[[user][:password]@]hostname[:[port]]]/path

See Essential CVS (O'Reilly) for a full explanation of each element of the repository path.

e editor

Use the specified editor when CVS calls an editor for log information during the commit or import process. This option overrides the EDITOR, CVSEDITOR, and VISUAL environment variables, and the contents of the .cvsrc file.

-f

Prevent CVS from reading the ~/.cvsrc file and using the options in it.

H, --help

If called as cvs -H or cvs --help, CVS displays a general CVS help message.

If called as cvs -H command or cvs --help command, CVS displays the available options and help information for the specified command.

-help-commands

List the available CVS commands with brief descriptions of their purposes.

-help-options

List the available cvs-options with brief descriptions of their purposes.

-help-synonyms

List the valid synonyms (short names) for the CVS commands.

-l

Do not log the current command to the history file in the repository's CVSROOT directory. The command will not show in subsequent cvs history output.

-n

Execute only commands that do not change the repository. Using this option with cvs update can provide a status report on the current sandbox.

-q

Run in quiet mode. This option causes CVS to display only some of the informational messages.

-Q

Run in very quiet mode. This option causes CVS to display only the most critical information.

-r

Set files checked out to the sandbox as read-only. This option only sets newly checked-out files. If a file is being watched with cvs watch, read-only is the default. This option overrides settings in the .cvsrc file.

s variable=value

Set a user variable for use with one of the scripting files in CVSROOT. The user variables are explained in CVSROOT Variables," later in this chapter.

-t

Display messages that trace the execution of the command. This option can be used with -n to determine precisely what a command does.

T directory

Use the named directory to store temporary files. This option overrides environment variables or settings in the .cvsrc file.

v, --version

Display CVS version and copyright information.

-w

Set files checked out to the sandbox as readable and writable. This option sets only the permissions of newly checked-out files. This option overrides the CVSREAD environment variable, and it overrides settings in the .cvsrc file.

-x

Encrypt all data that travels across the network between the client and the server. This option is currently available in GSS-API or Kerberos mode only, but if you use ssh as your rsh replacement in the ext connection mode, ssh encrypts the data stream.

This option is available only if the client supports it. It is supported if it is listed in cvs --help-options. You can compile the command-line client to support it by using the --enable-client and --enable-encryption options to the configure script.

z n

Compress all network traffic by using the specified gzip compression level n. The compression levels range from 0 (no compression) to 9 (maximum compression). This option overrides settings in the .cvsrc file.

This option is available only if the client supports it. It is supported if it is listed in cvs --help-options. You can compile the command-line client to support it by using the --enable-client option to the configure script.

Common Subcommand Options

Many of the CVS subcommands (add, commit, and so on) share a large number of common options. They are described here.

d directory-name

Check out or update a sandbox out into a directory called directory-name instead of using the repository directory name or the name designated in the modules file in the repository's CVSROOT directory. This is particularly useful when creating a second sandbox for a project.

CVS usually creates the same directory structure that the repository uses. However, if the checkout parameter contains only one file or directory and the -d option is used, CVS does not create any intervening directories. Use -N to prevent CVS from shortening the path.

D date

Run the subcommand on the latest revision of a file that is as old as or older than the date or time specified by date.

-f

Use the latest (HEAD) revision of a file that is on the current branch or trunk if no revision matches a specified date or revision number. This option applies only if -r or -D is used.

k mode

Specify the keyword expansion mode. For cvs add, this option also sets the default keyword mode for the file. If you forget to set the default keyword mode with cvs add, you can do so later with cvs admin. The keyword-expansion modes are listed in Keywords and Keyword Modes," later in this chapter

-l

Run the subcommand on the files in the local directory only. (Do not recurse into subdirectories.) See also -R.

m message

Use the specified message as the description of the newly added file or as the description of the change made.

-n

Do not run any program listed in the modules file for this directory.

-N

Do not shorten the path. CVS usually creates the same directory structure that the repository uses. However, if the checkout contains only one file and the -d option is used, CVS does not create any intervening directories unless -N is also specified.

r revision

Run the subcommand on the specified revision or tag of a file. If this option refers to a branch, run the command on the latest (HEAD) revision of the branch.

-R

Run the subcommand on the files in the local directory and all subdirectories and recurse down the subdirectories. This option is generally the default. See also -l.


Dot Files

In client/server mode, all the dot files other than .rhosts should be on the client computer. The .rhosts file should be in the user's home directory on the server computer.

These are the dot files in the sandbox directory:

.cvsignore

Contains a list of files CVS should not process. The format is one or more lines, with whitespace-separated filenames or shell wildcard patterns matching files that CVS should ignore when producing informational messages and during commit, update, or status operations. A single ! causes CVS to empty out its ignore list and start over again with subsequent filenames or patterns. The file may be checked into CVS.

.#filename.revision

If a project file that is not fully synchronized with the repository is overwritten by CVS, the original file is stored as .#filename.revision, where revision is the BASE revision of the file.

These are the dot files in a user's home directory:

.cvsignore

Contains a list of files CVS should not process. See the earlier description.

.cvspass

Used in pserver remote-access mode. This file contains the user's password for each repository they are logged into, stored in a simple form of encoding. Be aware that the file is human-readable and that the passwords are easy to decrypt.

.cvsrc

Contains a list of CVS commands and the options the user wants as default options for those commands.

.cvswrappers

Contains a list of wrappers that affect how a file is stored. The wrappers include a pattern that CVS matches against filenames and a keyword-expansion mode that CVS applies to any file whose name matches the pattern.

.rhosts

Used when connecting with rsh. This file should be in the user's home directory on the server machine, and it should contain the client's computer and username.

The rsh command is unacceptably insecure. You should avoid it completely; use ssh instead.


Environment Variables

Several environment variables affect CVS. Some are read-only when CVS is the client, and some are read-only when CVS is the server. When the repository resides on the local machine, both sets are read.

Client Environment Variables

The environment variables in the following list are read and used by the process that runs on the client computer and must be in the calling user's environment:

CVS_CLIENT_LOG

Used for debugging CVS in client/server mode. If set, everything sent to the server is stored in the $CVS_CLIENT_LOG.in file, and everything received by the client is stored in $CVS_CLIENT_LOG.out.

CVS_CLIENT_PORT

Used to set the port the client uses to connect to the CVS server in kserver, gserver, and pserver modes. By default, the client uses port 2401 (gserver and pserver) or port 1999 (kserver) to connect to the server.

CVSIGNORE

A whitespace-separated list of filename patterns that should be ignored. See the description of the .cvsignore file, earlier in this chapter.

CVSEDITOR, EDITOR, VISUAL

Used to set the editor CVS calls when it opens an editor for log messages. On Unix and GNU/Linux systems, the default editor is vi. Using CVSEDITOR is preferred over EDITOR and VISUAL, as other variables may be used by other programs.

CVS_PASSFILE

Used to change the file CVS uses to store and retrieve the password in pserver remote-access mode. The default file is $HOME/.cvspass.

CVSREAD

If set to 1, CVS tries to check out your sandbox in read-only mode. (CVS actually checks whether this variable is nonnull, so it works regardless of the setting. This behavior may change in the future.)

CVSROOT

Contains the full pathname of the CVS repository. When you're working in a sandbox, this variable is not needed. If you're working outside a sandbox, either this variable must be present or the -d repository_path option must be used.

CVS_RSH

Used to set the program CVS calls to connect to a remote repository in ext mode. The default program is rsh.

The rsh command is unacceptably insecure. You should avoid it completely; use ssh instead.

CVS_SERVER

If connecting to a CVS server using rsh, this variable is used to determine which program is started on the server side. In ext and server modes, this defaults to cvs. When the repository is on the local system, this defaults to the path to the CVS client program.

CVSWRAPPERS

May contain no more than one wrapper, as explained in CVS Wrappers," earlier in this chapter.

HOME, HOMEPATH, HOMEDRIVE

Used to determine where the user's home directory is, to enable CVS to locate its files. On Unix, GNU/Linux, and related systems, only HOME is used. On Windows systems, HOMEDRIVE and HOMEPATH are used. Some Windows operating systems (Windows NT, 2000, and XP) set these variables automatically. If yours doesn't, HOMEDRIVE should be set to the drive letter (e.g., C:), and HOMEPATH should be set to the path (e.g., \home\arnold).

PATH

Used to locate any programs whose path is not compiled with the CVS program. This variable is still used, but it is less important now that the rcs, diff, and patch programs CVS uses are all distributed with CVS.

Server Environment Variables

The following variables are read when CVS is operating as the server (or when the repository is on the local system). They must be in the calling user's environment on the server computer.

CVS_SERVER_SLEEP

Used only when debugging the server in client/server mode. This variable delays the start of the server client process by CVS_SERVER_SLEEP seconds to allow the debugger to be attached to it.

CVSUMASK

Used to set the default permissions of files in the repository. This variable may be added to the client code in a later version of CVS.

PATH

Used to locate any programs whose path is not compiled with the CVS program. This variable is still used, but it is less important now that the rcs, diff, and patch programs CVS uses are all distributed with CVS.

TMPDIR

Sets the temporary directory CVS stores data in. This variable defaults to /tmp.

CVS creates temporary files with mkstemp (BSD 4.3), if possible. If mkstemp is not available when CVS is compiled, it tries tempnam (SVID 3), mktemp (BSD 4.3), or tmpnam (POSIX), in that order. If it uses tmpnam, it cannot use the TMPDIR environment variable, and files are created in /tmp.


Keywords and Keyword Modes

CVS contains keywords that can be included in nonbinary project files. When CVS finds a keyword in a file it is checking out, it expands the keyword to provide metadata about the latest revision of the file. You can set keyword-expansion modes on a file to tell CVS whether (and how) to expand the keywords it finds.

Keyword-expansion modes also control line-ending conversion. Unix, Macintosh, and Windows operating systems use different sets of codes to signal the ends of lines. (GNU/Linux uses the same codes as Unix.) When you commit a file from an operating system that doesn't use Unix line endings, CVS converts the line endings to Unix style. If you are storing binary files, this conversion can corrupt the file. Use the -kb keyword-expansion mode to tell CVS not to convert line endings.

CVS keywords take the form:

$Keyword$

All keywords except Log expand to the format:

    $Keyword:
value$

These are the keywords and the information they show about the file they are in:

Author

The username of the user who committed the last revision.

Date

The date on which the last revision was committed, in UTC.

Header

A header containing information about the file, including the author, date and revision number, path and filename of the RCS file (project file in the repository), file status, and whether the file is locked.

Id

A header like the one given by the Header keyword, without the path of the RCS file.

Locker

The username of the user who locked the file with cvs admin -l (empty if the file is not locked).

Log

The commit messages, dates, and authors for the file. This keyword instructs CVS to store this information in the file itself. Any characters that prefix the keyword are also used to prefix log lines; this enables comment markers to be included automatically. Unlike most keywords, existing log expansions are not overwritten with the new ones; the new log expansions are merely prepended to the list.

The Log keyword is best used at the end of a file, to avoid users having to go through all the log messages to get to the important parts of the file.

This feature was inherited from RCS. As such, the log created by the Log keyword does not merge neatly when CVS merges a branch back to the trunk. If your file is likely to be branched and remerged, it is better to use the cvs log command than to store a log within the file.

NOTE

The cvs log command displays all the information that the Log keyword provides.

Name

The tag name the file was checked out with. This keyword can display a branch or provide a more meaningful identification of a revision than the revision number alone.

RCSfile

The name of the RCS file (the project file in the repository).

Revision

The CVS internal revision number of the file. This number is specific to the individual file and does not identify a stage within the project.

Source

The name and path of the RCS file (the project file in the repository).

State

The current state assigned to the current revision, set with cvs admin -s. See Chapter 7 in Essential CVS (O'Reilly).

The keyword-expansion modes in the following list are used in commands and CVS wrappers to control keyword expansion and line-ending conversion. The syntax differs slightly for each use. In commands, you use the mode without a space between the option and the mode (e.g., -kb). In wrappers, you need a space and may need to quote (e.g., -k 'b').

b

Inhibit keyword expansion and line-ending conversion. Use this keyword-expansion mode to signal that a file is binary. This option is needed because CVS can convert line endings from the form appropriate to the server to the form appropriate to the client. This causes obvious problems when working with binary files.

k

Generate only a keyword name, not a name and value. Use this option when merging different (nonbinary) versions of a file to prevent keyword substitution from creating spurious merge errors. This option can corrupt binary files.

o

Generate the version of a keyword string that was present just before the current file was last committed, rather than generating a version with the modifications of the last commit. This option is similar to -kb, but with line-ending conversion.

v

Generate only the value of a keyword, rather than the name and value. This is most useful with cvs export, but do not use it for binary files. Once any keyword is removed from a file, further expansions are not possible unless the word is replaced.

kv

Generate the name and value of a keyword. This is the default mode.

kvl

Generate the name and value of a keyword and add the name of the locking user if the revision is locked with cvs admin -l.


Dates

In CVS, all dates and times are processed by a version of the GNU getdate function, which can translate dates and times given in several different formats. Case is always irrelevant when interpreting dates. Spaces are permitted in date strings, but in the command-line client, a string with spaces should be surrounded by quotes. If a year is 0 to 99, it is considered to be in the twentieth century.

If a time is not given, midnight at the start of the date is assumed. If a time zone is not specified, the date is interpreted as being in the client's local time zone.

Legal Date Formats

The legal time and date formats for CVS are defined by the ISO 8601 standard and RFC 822 as amended by RFC 1123. Other formats can be interpreted, but CVS is designed to handle only these standards.

ISO 8601

The basic ISO 8601 date format is as follows:

year-month-day
hours:minutes:seconds

All values are numbers with leading zeros to ensure that the correct number of digits are used. Hours are given in 24-hour time. This produces the structure YYYY-MM-DD HH:MM:SS, which is internationally acceptable and can be sorted easily. You can use a date, a time, or both.

If you're using ISO 8601 format with the hyphens, the full date is required in CVS. The YYYYMMDD date format is also acceptable and can be abbreviated to YYYYMM or YYYY.

The HH and HH:MM time formats are acceptable. Times can also be specified without the colon, so HHMMSS or HHMM are usable.

Be aware that HHMM may be misinterpreted as YYYY. Get into the habit of using separators.

In strict ISO 8601 format, a T is required between the date and the time, but CVS understands this format with or without the T. The ISO 8601 standard also states that a Z at the end of the string designates UTC (Universal Coordinated Time), but CVS does not recognize the use of Z.

RFC 822 and RFC 1123

RFCs 822 and 1123 define a precise time format:

    [DDD ,]
DD MMM
YYYY
HH:MM[:SS]
ZZZ

These are the terms in the format:

DDD

A three-letter day of the week.

DD

A two-digit date of the month.

MMM

A three-letter month.

YYYY

The year (it must be a four-digit year).

HH

Hours.

MM

Minutes.

SS

Seconds.

ZZZ

The time zone (can be the text abbreviation, a military time zone, or an offset from UTC in hours and minutes).

Legal Date Keywords

CVS also allows short English phrases such as "last Wednesday" and "a month ago" to be used in place of actual dates. Case is not significant, and CVS can understand plurals. These are the keywords it understands:

Month names

January, February, March, April, May, June, July, August, September, October, November, and December.

Month abbreviations

Jan, Feb, Mar, Apr, Jun, Jul, Aug, Sep, Sept, Oct, Nov, and Dec.

Days of the week

Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday.

Day abbreviations

Sun, Mon, Tue, Tues, Wed, Wednes, Thu, Thur, Thurs, Fri, and Sat.

Units of time

year, month, fortnight, week, day, hour, minute, min, second, and sec.

Relative times

tomorrow, yesterday, today, and now.

Meridian qualifiers

am, pm, a.m., and p.m.

Modifiers

a, last, this, next, and ago.

Sequences

first, third, fourth, fifth, sixth, seventh, eighth, ninth, tenth, eleventh, and twelfth. (second can't be used as a sequence term, because it is used as a time unit.)

Time Zones

CVS understands time zones expressed in offsets from UTC, such as +0700 (7 hours ahead) and -1130 (11 hours, 30 minutes behind). The format for these time zones is +HHMM or -HHMM, where + means ahead of UTC and - means behind UTC. CVS also understands time-zone abbreviations and ignores case and punctuation when interpreting them.

NOTE

Some of the time-zone abbreviations CVS recognizes are ambiguous. CVS recognizes only one meaning for each of the ambiguous time zones. However, the meaning that is recognized may vary depending on your operating system, and on how CVS was configured when it was compiled.

Table 13-2 shows the valid civilian time-zone abbreviations for CVS. Table 13-3 shows military time-zone abbreviations that CVS recognizes.

Table 13-2. Civilian time-zone abbreviations

Abbrev.

Offset / Name

Abbrev.

Offset / Name

gmt

+0000 Greenwich Mean

met

-0100 Middle European

ut

+0000 Coordinated Universal Time

mewt

-0100 Middle European Winter

utc

+0000 Coordinated Universal Time

mest

Middle European Summer

wet

+0000 Western European

swt

-0100 Swedish Winter

bst

+0000 British Summer (ambiguous with Brazil Standard)

sst

Swedish Summer (ambiguous with South Sumatra)

wat

+0100 West Africa

fwt

-0100 French Winter

at

+0200 Azores

fst

French Summer

bst

+0300 Brazil Standard (ambiguous with British Summer)

eet

-0200 Eastern Europe, USSR Zone 1

gst

+0300 Greenland Standard (ambiguous with Guam Standard)

bt

-0300 Baghdad, USSR Zone 2

nft

+0330 Newfoundland

it

-0330 Iran

nst

+0330 Newfoundland Standard (ambiguous with North Sumatra)

zp4

-0400 USSR Zone 3

ndt

Newfoundland Daylight

zp5

-0500 USSR Zone 4

ast

+0400 Atlantic Standard

ist

-0530 Indian Standard

adt

Atlantic Daylight

zp6

-0600 USSR Zone 5

est

+0500 Eastern Standard

nst

-0630 North Sumatra (ambiguous with Newfoundland Summer)

edt

Eastern Daylight

sst

-0700 South Sumatra, USSR Zone 6 (ambiguous with Swedish Summer)

cst

+0600 Central Standard

wast

-0700 West Australian Standard

cdt

Central Daylight

wadt

West Australian Daylight

mst

+0700 Mountain Standard

jt

-0730 Java

mdt

Mountain Daylight

cct

-0800 China Coast, USSR Zone 7

pst

+0800 Pacific Standard

jst

-0900 Japan Standard, USSR Zone 8

pdt

Pacific Daylight

cast

-0930 Central Australian Standard

yst

+0900 Yukon Standard

cadt

Central Australian Daylight

ydt

Yukon Daylight

east

-1000 Eastern Australian Standard

hst

+1000 Hawaii Standard

eadt

Eastern Australian Daylight

hdt

Hawaii Daylight

gst

-1000 Guam Standard, USSR Zone 9 (ambiguous with Greenland Standard)

cat

+1000 Central Alaska

nzt

-1200 New Zealand

ahst

+1000 Alaska-Hawaii Standard

nzst

-1200 New Zealand Standard

nt

+1100 Nome

nzdt

New Zealand Daylight

idlw

+1200 International Date Line West

idle

-1200 International Date Line East

cet

-0100 Central European

Table 13-3. Military time-zone abbreviations

Name

Offset

Name

Offset

Name

Offset

Name

Offset

Name

Offset

a

+0100

f

+0600

l

+1100

q

-0400

v

-0900

b

+0200

g

+0700

m

+1200

r

-0500

w

-1000

c

+0300

h

+0800

n

-0100

s

-0600

x

-1100

d

+0400

i

+0900

o

-0200

t

-0700

y

-1200

e

+0500

k

+1000

p

-0300

u

-0800

z

+0000


CVSROOT Variables

The administrative files in CVSROOT can use several types of variables: internal, environment, and shell variables. You can use these variables to pass parameters to the scripts in the scripting files, or you can use them as part of command-line templates.

The internal variables allow you to use information CVS stores about the currently running command. The environment variables are used to access information from the environment the command is running in, and the shell variables are used to access information about the shell.

Environment Variables in CVSROOT Files

Three environment variables are set when CVS runs commands or scripts from CVS administrative files:

CVS_USER

This variable is meaningful only with the pserver access method. It refers to the CVS username provided in the leftmost field of the appropriate line in CVSROOT/passwd. If this username does not exist, the variable expands to an empty string.

LOGNAME, USER

Both of these variables contain the username of the user calling the CVS process.

In the pserver access method, the username is the third field of the line in passwd. If no username is there, the CVS_USER value is used.

Internal Variables in CVSROOT Files

The syntax for referencing a CVS internal variable is ${VARIABLE}. The $VARIABLE syntax can also be used if the character immediately following the variable is neither alphanumeric nor an underscore (_).

These are the internal CVS variables:

CVSROOT

The path to the repository root directory (not the path to the CVSROOT directory within the repository). This variable contains the path only, not any access method or host information.

CVSEDITOR, EDITOR, VISUAL

The editor CVS is using. If you use the -e editor CVS option, CVS uses the editor you specify on the command line. If you don't use -e, CVS reads the environment variables and uses the first editor it finds. CVS uses CVSEDITOR by preference, then EDITOR, then VISUAL.

USER

The username (on the server machine in client/server mode) of the user running CVS.

With the pserver access method, this is the third field of the appropriate line in passwd. If no username is there, it is the name in the leftmost field.

CVS permits user-defined variables that can be passed to administrative files from the client. In the administrative files, reference such a variable with the syntax ${=VARIABLE}. On the command line, use the -s variable=value CVS option to pass the variable to CVS. All strings that contain the $ symbol, other than the variable references, are reserved for CVS internal use. There is no way to escape the $ symbol.

Shell Variables in CVSROOT Files

Two shell variables are also used in the administrative files:

~/

The home directory of the user calling the CVS process.

~username

The home directory of the user identified as username.


Alphabetical Summary of Commands

Most of your interaction with CVS is through the various CVS subcommands. Even if you use a graphical client, most of the functions the client uses call the CVS subcommands.

Most subcommands have a shortened nickname that you can type instead of the longer subcommand name. These are called command synonyms in CVS jargon.

add
cvs [cvs-options] add [-k mode] [-m message] files

Add a file or directory to the repository. This command can also be used to undo an uncommitted file deletion or to restore a deleted file. You must commit any added files in order for the addition to fully take effect.

Synonyms: ad, new

Standard subcommand options: -k, -m

Examples

$ cvs add Design.rtf
    cvs server: scheduling file `Design.rtf' for addition
    cvs server: use 'cvs commit' to add this file permanently

admin
cvs [cvs-options] admin [options] [files ...]

Use RCS commands on the repository copy of project files. This command is is a frontend for a range of useful (though sometimes useless to CVS) RCS-based commands. Project files are stored in the repository in RCS format, so it is useful to have a way to use some of the RCS commands on the files directly.

Synonyms: adm, rcs

Standard subcommand options: -k

Options

-ausernames

Append the comma-separated list of usernames to the RCS access list in the repository (RCS-format) copy of a file. This change to an RCS file has no effect on CVS. See also -A and -e.

-Afilename

Append the RCS access list in filename to the access list of the files being operated on. This change to an RCS file has no effect on CVS. See also -a and -e.

-b[revision]

Set the default branch of a file to the named branch revision; if no revision is named, set the default branch to the highest branch revision on the trunk. This option should be used very rarely in CVS; it is better to check out a sandbox as a branch sandbox with the -r option to checkout or update.

-cstring

Set the RCS comment leader of a file to the specified string. This option is not used in CVS.

-e[usernames]

Remove the comma-separated list of usernames from the RCS access list in the repository (RCS-format) copy of a file. If no list of usernames is provided, remove all names. This change to an RCS file has no effect on CVS. See also -a and -A.

-i

Create and initialize an RCS file. This option is not used in CVS (use cvs add instead), and it is not available in CVS 1.9.14 and later.

-I

Run interactively. This option does not work in client/server-mode CVS and may be removed from later versions of CVS.

-l[revision]

Lock the specified revision of a file so that another user cannot commit to it. If revision is omitted, CVS locks the latest revision on the current sandbox's branch or the trunk. To work with CVS, the lock requires a script such as the rcslock script in the contrib directory of the source. See Essential CVS (O'Reilly) for how to use this option. See also -u.

-L

Set RCS locking for a file to strict, which means that the owner of the file must lock the file before committing. (This locking is done by the CVS code, and need not be done manually.) File locking must be set to strict for CVS to work properly. See also -U.

-mrevision:message

Replace the log message of the designated revision of a file with the specified message.

-ntagname[:[revision]]

Tag the designated revision or branch of a file with the tagname. If there is no revision and no colon, delete the tag; if there is a colon but no revision, tag the latest revision on the default branch, usually the trunk. If the tagname is already present in the file (and the operation isn't "delete"), this option prints an error and exits. See also -N.

Generally, it is better to use cvs tag and cvs rtag to manipulate tags.

-Ntagname[:[revision]]

Tag the designated revision or branch of a file with the tagname. If there is no revision and no colon, delete the tag; if there is a colon but no revision, tag the latest revision on the default branch, usually the trunk. If the tagname is already present in the file (and the operation isn't "delete"), this option moves the tag to the new revision. See also -n.

Generally, it is better to use cvs tag and cvs rtag to manipulate tags.

-orange

Delete the revisions specified in the range. The revisions given in the range can be revision numbers or tags, but be wary of using tags if multiple tags in a file denote the same revision.

There is no way to undo a cvs admin -o command.

The range can be any of the following:

revision1:revision2

Delete revisions between revision1 and revision2, including revision1 and revision2.

revision1::revision2

Delete revisions between revision1 and revision2, excluding revision1 and revision2.

revision:

Delete revision and all newer revisions on the same branch (or the trunk).

revision::

Delete all revisions newer than revision on the same branch (or the trunk).

:revision

Delete revision and all older revisions on the same branch (or the trunk). This range does not delete the base revision of the branch or revision 1.1.

::revision

Delete all revisions older then revision on the same branch (or the trunk). This range does not delete the base revision of the branch or revision 1.1.

revision

Delete revision.

-q

Run quietly, without printing diagnostics (redundant with cvs -q admin).

-sstate[:revision]

Set the state of the designated revision of a file, or set the last revision on the trunk or the current branch if no revision is listed. The state should be a string and is shown in the output of cvs log and by the Log and State keywords. The dead state is reserved for CVS internal use.

-t[filename]

Write the contents of the file specified by filename to the description of each file listed in the command. The description is an RCS field, shown in cvs log output. This option deletes any existing description. If the filename is omitted, CVS seeks input from standard input, ending with a period (.) on a line by itself. See also -t-string.

-t-string

Write the contents of the string to the description of each file listed in the command. The description is an RCS field, shown in cvs log output. This option deletes any existing description. See also -t.

-u[revision]

Unlock the specified revision of a file so that another user can commit from that revision. If the revision is omitted, this option unlocks the latest revision on the current sandbox's branch or the trunk. This option requires a script, such as the rcslock script in the contrib directory of the source. See Essential CVS (O'Reilly) for how to use this option. See also -l.

-U

Set RCS locking for a file to nonstrict, which means that the owner of the file does not need to lock the file before committing. (This locking is done by the CVS code and need not be done manually.)

File locking must be set to strict for CVS to work properly. This option should never be used on CVS-stored files. See also -L.

-Vn

Write an RCS file compatible with RCS version n. This option is not used in CVS anymore, and it is not available in CVS 1.9.20 and later.

-xsuffix

Specify the suffix for the RCS file. This option is not used or available in CVS (all CVS files use ,v as the suffix).

Examples

$ cvs admin -kb AcceptanceTest.doc
RCS file: /var/lib/cvs/wizzard/doc/design/AcceptanceTest.
doc,v
done

annotate
cvs [cvs-options] annotate [options] [files ...]

Display a file or files with annotations showing the last editor and revision that changed each line of the file. If no files are used in the argument, the files in the current sandbox are shown. See also rannotate.

Synonym: ann

Standard subcommand options: -D, -f, -l, -r, -R

Options

-F

Show annotations for binary files.

Examples

$ cvs annotate Makefile

Annotations for Makefile
***************
1.2  (arnold     01-Sep-02): #
1.2 (arnold     01-Sep-02): # Makefile for the Wizzard
project
1.2 (arnold     01-Sep-02): # Created by A Robbins, 1
September 2002

checkout
cvs [cvs-options] checkout [options] projects ...

Create a new sandbox in the current working directory. This command can also be used to update an existing sandbox. See also export and update.

The projects argument to checkout may be one or more paths to directories within the repository, paths to files within the repository, or module names as specified in the modules file in the repository's CVSROOT directory. These paths must be separated by spaces.

When creating a new sandbox, the repository path must be specified by using the -d repository_path CVS option or the CVSROOT environment variable.

If you are creating a new sandbox inside an existing sandbox, the CVS/Root file of the current directory in the existing sandbox can provide a repository path. In most cases, having a sandbox inside a sandbox is needlessly confusing.

Synonyms: co, get

Standard subcommand options: -d, -D, -f, -k, -l, -n, -N, -r, -R

Options

-A

Clear sticky tags, dates, and keyword-expansion modes from a project and replace the current files with the head of the trunk.

-c

Display the contents of the modules file in the repository's CVSROOT directory. This option lists the modules in the current repository and the options applicable to those modules. See also -s.

NOTE

checkout -c lists only those projects that have entries in the modules file.

-j revision[:date]

Determine the changes between the revision the files in the sandbox are based on and the specified revision and merge those changes to the sandbox.

If two -j options are used, determine the changes between the first -j revision and the second -j revision and merge those changes to the sandbox.

The date can be used only if the revision designates a branch. date specifies the latest revision on that date.

-p

Check out the listed files to standard output, rather than to the filesystem.

-P

Do not include empty directories in the sandbox.

-s

Display the contents of the modules file in the repository's CVSROOT directory. This option lists the modules in the current repository and their status. See also -c.

Examples

$ cvs -d cvs:/var/lib/cvs checkout wizzard
cvs server: Updating wizzard
U wizzard/Changelog
U wizzard/INSTALL
U wizzard/Makefile

commit
cvs [cvs-options] commit [options] [files ...]

Commit changes in a sandbox to the repository. Until a commit is run, changes such as modified, new, or removed files are not reflected in the repository. If no files are listed as arguments, CVS uploads all changes in the current sandbox.

Unless you use either the -m or -F options, commit calls an editor to request a log message.

If there have been changes in the repository version of a file since it was last synchronized with the repository, and the local version has also changed, you have a conflict and the file cannot be committed. You can try to commit the file again once you have updated it using cvs update or cvs checkout. The update will include an attempt to merge the file.

Synonyms: ci, com

Standard subcommand options: -l, -m, -n, -r, -R

Options

-f

Force CVS to commit a file even if there have been no changes to the file. This option implies the -l option.

-F logfile

Read a log message from the specified logfile rather than calling an editor.

Examples

/home/arnold/cvs/wizzard$ cvs commit
cvs commit: Examining .
cvs commit: Examining doc
cvs commit: Examining lib
...
RCS file: /var/lib/cvs/wizzard/doc/design/Design.rtf,v
done
Checking in doc/design/Design.rtf;
/var/lib/cvs/wizzard/doc/design/Design.rtf,v <--  Design.
rtf
initial revision: 1.1
done

diff
cvs [cvs-options] diff [format-options] [options] [files ...]

Display the differences between two revisions of a file or files. By default, diff checks the sandbox copy against the revision in the repository that the sandbox copy was last synchronized with. If the files argument is a directory, all files under that directory are compared, and files in subdirectories are also compared recursively. See also rdiff.

Synonyms: di, dif

Standard subcommand options: -D, -k, -l, -r, -R

The format-options determine how cvs diff displays any differences it finds. They operate in the same way as the options to the GNU diff program. See the entry for diff in Chapter 3.

Line and group format options

Line and group formats allow you to modify the way diff displays line changes. The group format options control the markers that surround the change, and the line format options control the marks on the changed lines themselves. Group format options are often used to create if-then-else structures for automated parsers to use.

The format options have a format string as a parameter and display the lines they affect according to the rule provided in the format string. The format string usually contains characters that are interpreted by your operating system's shell, so the string usually needs to be surrounded by your shell's quote character.

Following are the group format options, which affect the markers surrounding changed lines:

--changed-group-format=format-string

Display the text defined by the format string for each group of lines that are different between files, usually a concatenation of the old and new group format strings.

--new-group-format=format-string

Display the text defined by the format string for each group of lines from the second file that are different or missing in the first file.

--old-group-format=format-string

Display the text defined by the format string for each group of lines from the first file that are different or missing in the second file.

--unchanged-group-format=format-string

Display the text defined by the format string for each group of lines that are the same in both files.

Here are the line format options, which affect the lines themselves:

--line-format=format-string

Display the text defined by the format string for all lines.

--new-line-format=format-string

Display the text defined by the format string for each line from the second file that is different or missing in the first file.

--old-line-format=format-string

Display the text defined by the format string for each line from the first file that is different or missing in the second file.

--unchanged-line-format=format-string

Display the text defined by the format string for each line that is the same in both files.

The format-string for both group and line formats uses the percent (%) character as a special token, denoting a string to be evaluated by cvs diff. The string %% represents a single percent character. You also need to know your shell's quoting rules if you wish to include your shell's quote marks in the format string.

These are the special characters for a line format-string:

%c'C'

The character C, which cannot be a quote or a backslash.

%c'\O'

The character represented by the octal string O.

%l

The contents of the line to be formatted, not including the newline character.

%L

The contents of the line to be formatted, including the newline character. If a line does not contain a newline character, this character does not add it.

%[-][width][.[digits]][doxX]n

A printf-style format-string that displays the line number of the current line. The hyphen (-) signals that the number should be left-justified. The width specifies the minimum field width, and digits specifies the minimum number of digits. The other options are d (for decimal), o (for octal), and x or X (for lowercase or uppercase hexadecimal).

%%

The percent character.

These are the special characters for a group format-string:

%<

The lines from the first file.

%>

The lines from the second file.

%=

Lines common to both files.

%[-][width][.[digits]][doxX]symbol

A printf-style format-string that displays the number denoted by symbol. The hyphen (-) signals that the number should be left-justified. The width specifies the minimum field width, and digits specifies the minimum number of digits. The other options are d (for decimal) o (for octal), and x or X (for lowercase or uppercase hexadecimal).

Lowercase symbols denote the first file. Uppercase symbols denote the second file. The symbols are:

E, e

The line number of the line just before the group.

F, f

The line number of the first line in the group.

L, l

The line number of the last line in the group.

M, m

The line number of the line just after the group.

N, n

The number of lines in the group.

%(A=B?C:D)

If A is equal to B, display C; otherwise, display D. A and B must be decimal constants or a single letter that is one of the symbols provided.

%%

The percent character.

%c'C'

The character C, which cannot be a quote or a backslash.

%c'\O'

The character represented by the octal string O.

Examples

This is a simple example to show how CVS displays the difference between the current and repository revisions of the Makefile.

$ cvs diff Makefile
Index: Makefile
=  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==
RCS file: /var/lib/cvs/wizzard/Makefile,v
retrieving revision 1.6
diff -r1.6 Makefile
25a26
>       rm -f lib/*.o

edit
cvs [cvs-options] edit [options] [files ...]

Mark a file as being edited by the current user. This command is used as part of the cvs watch family of commands. If a file is being watched, it is checked out to the sandbox with read permissions but not write permissions. The edit command sets the sandbox file as writable, notifies any watchers that the file is being edited, and sets the user as a temporary watcher to be notified if certain actions are performed on the file by other users. See also editors, unedit, watch, and watchers.

NOTE

CVS does not notify you of your own changes.

You can unedit (set read-only and clear the temporary watch) a file with cvs unedit or cvs release, or by removing the file and re-creating it with cvs update or cvs checkout.

CVS uses any script in the notify file in the repository's CVSROOT directory to notify the user of changes.

Synonyms: none

Standard subcommand options: -l, -R

Options

-a action

Notify the user when the specified action occurs to the file. This setting acts as a temporary watch (see watch) on the file and is removed when the file is no longer being edited. Each -a designates one of the possible actions. The -a option can be repeated to designate multiple actions.

The action may be any of the following:

commit

Notify the user when someone else commits changes to the file.

edit

Notify the user if someone else has run cvs edit on the file.

unedit

Notify the user when the file is no longer being edited by someone else. This notification is triggered by the user running cvs unedit or cvs release, or by the file being deleted and re-created with cvs update or cvs checkout.

all

Notify the user of all of the previous actions.

none

Notify the user of none of the previous actions.

editors
cvs [cvs-options] editors [-lR] [files ...]

Displays the list of people who have a current edit command for the file or files listed as parameters. If no files are listed, this command lists the editors for the files in the current directory and subdirectories. See also edit, unedit, watch, and watchers.

Synonyms: none

Standard subcommand options: -l, -R

Examples

$ cvs editors Makefile
Makefile arnold Sat Oct 26 01:51:02 2002 GMT helit /home/
arnold/cvs/wizzard

export
cvs [cvs-options] export [options] project

Create a directory containing all directories and files belonging to a specified release of a project, with no CVS administrative files. It acts like a checkout or update for that specific point, but it does not produce the CVS administrative files. export requires the -r or -D command options. When exporting, the repository path must be specified by using the -d repository_path CVS option or the CVSROOT environment variable. See also checkout and update.

The argument to export can be a directory name or path within the repository, a filename or path within the repository, or a module name as specified in the modules file in the repository's CVSROOT directory.

NOTE

You can imply the repository path by being in a sandbox, but exporting into a sandbox is not recommended.

Synonyms: exp, ex

Standard subcommand options: -d, -D, -f, -k, -l, -n, -N, -r, -R

Examples

$ cvs -d cvs:/var/lib/cvs export -D now wizzard
cvs server: Updating wizzard
U wizzard/Changelog
U wizzard/INSTALL
U wizzard/Makefile

history
cvs [cvs-options] history [options] [files ...]

Display the information stored in the history file in the repository's CVSROOT directory. If that file does not exist or is not writable, the history command fails with an error. CVS writes to the history file during checkout, export, commit, rtag, update, and release operations.

Synonyms: hi, his

Standard subcommand options: -D, -r

NOTE

The -f, -l, -n, and -p options for cvs history act differently than their normal uses in CVS.

Options

-a

Show history data for all users. By default, CVS shows only the data for the calling user.

-b string

Show data more recent than the newest record that contains the given string in the module name, filename, or repository path.

-c

Report only commits: times when the repository was modified (equivalent to -xAMR).

-e

Report on every record type. This option is equivalent to -x with every type specified.

-f file

Show data for the specified file. This option can be repeated to show data for multiple files.

-l

Show only the most recent commit to the repository.

-m module

Show data for a particular module. CVS checks the modules file in the repository's CVSROOT directory and then searches the history file for files and directories that belong to the module.

-n module

Like -m, but CVS searches only the history file for the specified module name.

-o

Report on records of checkouts (equivalent to -xO).

-p directory

Show records for a particular project directory. This option can be repeated to show records for several projects.

-r revision

Show data as of, or more recent than, the revision or tag. CVS searches the repository's project files to determine the timestamp of the revision.

-t tagname

Show data as of, or more recent than, the latest time a tag record with this tagname was stored in the history file by any user.

-T

Report on records of tags (equivalent to -xT).

-u username

Report on records for the specified username. This option can be repeated to search for multiple users.

-w

Report on records of actions that match the current working directory.

-x flag(s)

Extract records that match the given flag or flags. Any number of flags can be used with the -x option. cvs history extracts all records in the history file that match this option and all other options. The flags may be any of the following:

A

Report on records of files added to the repository.

C

Report on records of files that would have been updated in a sandbox, but where the files needed to be merged and there were conflicts in the merge.

E

Report on records of files exported from the repository.

F

Report on records of files that were released.

G

Report on records of files updated in a sandbox with a successful merge.

M

Report on records of files that were modified (a sandbox revision added to the repository).

O

Report on records of files that were checked out.

R

Report on records of files that were removed from the repository.

T

Report on records of files that were rtagged.

U

Report on records of files updated in a sandbox file with no merge required.

W

Report on records of files deleted from a sandbox during an update because they were no longer active in the repository.

-z timezone

Produce output and convert times to the specified timezone. The time zone can be a recognized abbreviation such as EST, or it can be given as an offset of UTC. Time zones are listed in the earlier section Time Zones."

Examples

$ cvs history
O 2002-10-03 08:33 +0000 arnold wizzard/src =wizmain=
<remote>/*
O 2002-10-03 09:12 +0000 arnold wizzard     =wizmake=
<remote>/*
O 2002-10-03 09:12 +0000 arnold wizzard/src =wiztest=
<remote>/*
O 2002-10-25 08:58 +0000 arnold wizzard     =wizzard=
<remote>/*

import
cvs [cvs-options] import [options] project-name vendor-tag
release-tag

Create a new project in the repository, or manage vendor branches. To create a new project, lay out the project structure and any initial files. You can do this in a temporary directory, as CVS does not need the initial structure or files once the project has been imported. Change directories into the root directory of the new project; then run cvs import. You need to specify the repository path and provide a project name and two tags: a vendor tag and a release tag.

The project-name will become the project's root directory name. The tags are less critical; if you do not intend to use a vendor branch, a meaningless pair of tags such as a1 b2 is sufficient. The tag names must conform to all the normal requirements for tags: they must start with a letter and can contain only alphanumeric characters, underscores (_), and hyphens (-). The HEAD and BASE tag names are reserved.

A vendor branch is a special branch that CVS provides to track third-party code that contributes to a project. If you use vendor branches, CVS uses the vendor-tag as a branch tag for the vendor branch, and it uses the release-tag to mark the current revisions of the vendor branch files.

Create a vendor branch by using cvs import to create the project. When you want to update to a new release from the vendor, use cvs import on the same project with the same vendor tag and a new release tag.

NOTE

Test that you can cvs checkout the new project before removing the original files.

Synonyms: im, imp

Standard subcommand options: -k, -m

Options

-b branch

Import to the specified vendor branch. If you have more than one external supplier for a project, you may need to use two or more distinct vendor branches to manage the project. If you are using multiple vendor branches, use the -b option to specify which branch you are importing to. branch must be the branch number, not a tag, and CVS does not check that the branch number given with the option and the symbolic tag provided as the vendor-tag argument to the command correspond to the same branch.

-d

When setting the timestamp on each imported file, use each file's last modification time rather than the current time.

-I file

Ignore the named file when updating. -I can be used more than once. Use -I ! to clear the list of ignored files.

-W wrapper

Modify the import based on elements of each filename.

Examples

$ cvs -d cvs:/var/lib/cvs import wizzard wizproject ver_0-
1
...
No conflicts created by this import

init
cvs [cvs-options] init

Convert an existing directory into a CVS repository, and create and populate the CVSROOT directory that contains the administrative files for a CVS repository.

CVS creates the final directory in the path if it does not already exist. Previous directories in the path must exist.

Synonyms: none

Examples

$ cvs -d /var/lib/cvsroot init

kserver
cvs [cvs-options] kserver

Run the repository-server end of a Kerberos 4 connection. The cvs kserver command must be called from inetd or an equivalent server daemon. See also pserver.

Synonyms: none

log
cvs [cvs-options] log [options] [files ...]

Display information about the files in the current sandbox or the files specified as parameters. The information this command provides is part of the header section of the files in the repository. This command also provides information from the log messages created when files are imported or changes are committed.

With no options, cvs log displays all the information it has available. See also rlog.

Synonym: lo

Standard subcommand options: -l

Options

-b

Display information about only the revisions on the default branch, normally the trunk.

-d dates

Display information only on revisions checked in on or between the dates or times provided. Date and time formats are listed in the earlier section "Dates." More than one date range can be given; ranges must be separated by semicolons. Date ranges can be specified according to the following list:

date1>date2, date2<date1

Select all revisions between the two dates.

date1>=date2, date2<=date1

Select all revisions on or between the two dates.

date>, <date

Select all revisions earlier than date.

date>=, <=date

Select all revisions on or earlier than date.

date<, >date

Select all revisions later than date.

date<=, >=date

Select all revisions on or later than date.

date

Select all revisions on date.

-h

Print only the header information for a file, not the description, the log messages, or revision information.

-N

Do not list the tags (the symbolic names).

-r[revisions]

Provide information only on revisions in the ranges provided. More than one range can be given; ranges must be separated by commas. There must be no space between the -r and its argument. If no range is provided, the latest revision on the default branch, normally the trunk, is used.

Ranges can be specified according to the following list:

revision1:revision2, revision1::revision2

Select all revisions between revision1 and revision2. The revisions must be on the same branch. With the double colon, CVS excludes revision1.

:revision, ::revision

Select revisions from the start of the branch or trunk the revision is on, up to and including the revision.

revision:, revision::

Select revisions from revision to the end of the branch or trunk the revision is on. With the double colon, CVS excludes the revision.

branch

Select all revisions on branch.

branch1:branch2, branch1::branch2

Select all revisions on both branches and any branches that split off from the two branches.

branch.

Select the latest revision on branch. Note the trailing period.

-R

Display the name of the repository copy of a file only.

-s states

Display only revisions with states that match one of the states in the comma-separated list.

-S

Do not display header information if there are no revisions to display.

-t

Print only the header information and description, not the log messages or revision information.

-w[usernames]

Display only revisions committed by the specified list of users. Provide the list of users as a comma-separated list. If no usernames are listed, the revisions committed by the current user are displayed. There can be no space between -w and its argument.

Examples

$ cvs log
cvs server: Logging .

RCS file: /var/lib/cvs/wizzard/Changelog,v
Working file: Changelog
head: 1.1
branch:
locks: strict
access list:
symbolic names:
beta_0-1_branch: 1.1.0.2
beta_0-1_branch_root: 1.1
pre_beta_0-1: 1.1
keyword substitution: kv
total revisions: 1;
selected revisions: 1
description:
----------------------------
revision 1.1    da
te: 2002/08/31 13:37:56;   author: arnold;  state: Exp;
Creating a structure.
...

login
cvs [cvs-options] login

Log into a CVS pserver session. This command is needed only with the pserver connection mode. See also logout.

Synonyms: none

Examples

$ cvs -d :pserver:arnold:password:@cvs.nosuch.net:/var/
lib/cvs login
Logging in to :pserver:arnold@cvs:2401/var/lib/cvs

logout
cvs [cvs-options] logout

Log out of a CVS pserver session. This command is needed only with the pserver connection mode. See also login.

Synonyms: none

Examples

$ cvs -d :pserver:arnold@cvs:/var/lib/cvs logout
Logging out of :pserver:arnold@cvs:2401/var/lib/cvs

pserver
cvs [cvs-options] pserver

Run the repository-server end of a password server or Kerberos 5 (via the GSS-API) connection. This command must be called from inetd or an equivalent server daemon. See also kserver.

Synonyms: none

rannotate
cvs [cvs-options] rannotate [options] files
...

Display files with annotations showing the last editor and revision that changed each line of each specified file. You can run rannotate without a sandbox, but you must have a repository specified if you do so. rannotate requires at least one filename, directory name, or module name from within the repository as an argument. See also annotate.

Synonyms: ra, rann

Standard subcommand options: -D, -f, -l, -r, -R

Options

-F

Show annotations for binary files.

Examples

$ cvs rannotate wizzard/Makefile

Annotations for wizzard/Makefile
***************
1.2  (arnold 01-Sep-02): #
1.2  (arnold     01-Sep-02): # Makefile for the Wizzard
project
1.2  (arnold     01-Sep-02): # Created by A Robbins, 1
September 2002

rdiff
    cvs [cvs-options] rdiff [options] projects ...

Create output that can be redirected into a file and used with the GNU (or equivalent) patch program. The output goes to the standard output. rdiff operates directly from the repository and does not need to be used from a sandbox. It does, however, require a filename, directory name, or module name as an argument, and you must specify one or two revisions or dates. If you specify one revision or date, rdiff calculates the differences between that date and the current (HEAD) revision. If two dates are specified, rdiff calculates the differences between the two. See also diff.

Synonyms: pa, patch

NOTE

Most people use rdiff to make a file to use with patch. If you're using a patch file that was created over more than one directory, you may need to use the -p option to patch, so that it can find all the appropriate directories.

Standard subcommand options: -D, -f, -l, -r, -R

Options

-c

Use context output format, with three lines of context around each change. This is the default format.

-s

Create a summary change report rather than a patch, showing which files have changed with one line per file.

-t

Produce a report on the two most recent revisions in a file. Do not use -r or -D with the -t option.

-u

Use unidiff format instead of context format.

-V version

This option is now obsolete, but it used to allow you to expand keywords according to the rules of the specified RCS version.

Examples

$ cvs rdiff -r 1.5 wizzard/Makefile
Index: wizzard/Makefile
diff -c wizzard/Makefile:1.5 wizzard/Makefile:1.6
*** wizzard/Makefile:1.5     Thu Oct 17 08:50:14 2002
--- wizzard/Makefile         Thu Oct 17 10:01:12 2002
***************
*** 2,17 ****
      # Makefile for the Wizzard project
      # First created by A Robbins, 1 September 2002
      #
    ! # Current revision $Revision: 1.4 $
      # On branch $Name:  $ (not expanded if this is the trunk)
    ! # Latest change by $Author: sanders $ on $Date: 2005/05/
    03 19:07:12 $
      #
      ##

      # Initial declarations
      #
      CC=gcc
    ! SUBDIRS = man doc src lib

      # Declaring phony targets
    --- 2,17 ----
      # Makefile for the Wizzard project
      # First created by A Robbins, 1 September 2002
      #    ! # Current revision $Revision: 1.4 $
      # On branch $Name:  $ (not expanded if this is the trunk)
    ! # Latest change by $Author: sanders $ on $Date: 2005/05/
    03 19:07:12 $
      #
      ##

      # Initial declarations
      #
      CC=gcc
    ! SUBDIRS = man doc src lib test

      # Declaring phony targets
    ***************

    ...

release
cvs [cvs-options] release [-d] directories ...

Make a sandbox inactive. This command checks for uncommitted changes, removing any existing edit flags, and writes to the CVSROOT/history file that the sandbox has been released. You can use release on an entire sandbox or on one or more subdirectories.

Synonyms: re, rel

Option

-d

Delete the sandbox after it has been released.

Examples

$ cvs -d cvs:/var/lib/cvs release wizzard
You have [0] altered files in this repository.
Are you sure you want to release directory `wizzard': y

remove
cvs [cvs-options] remove [-flR] [files ...]

The remove command removes a file or directory from the repository. It can also be used to undo an uncommitted file addition.

Synonyms: rm, delete.

Standard subcommand options: -l, -R.

Options

-f

Delete the files from the sandbox before removing them from the repository.

Examples

$ cvs remove server.cc
cvs server: scheduling `server.cc' for removal
cvs server: use 'cvs commit' to remove this file
permanently

rlog
cvs [cvs-options] rlog [options] files ...

The rlog command is a remote version of the log command. rlog works without a sandbox and requires a file, directory, or module name from the repository. See also log.

Synonym: rl.

Standard subcommand options: -l.

Options

-b

Provide information about only the revisions or a file on the default branch, normally the highest branch on the trunk.

-d dates

Provide information on only revisions of a file that were checked in on or between the dates or times provided. Date formats are listed in the earlier section Dates." More than one date range can be given; ranges must be separated by semicolons. Date ranges are the same as for the log command (see log).

-h

Print only the header information, not the description, log messages, or revision information.

-N

Do not list the tags (the symbolic names).

-r[revisions]

Provide information on only revisions in the ranges provided. More than one revision range can be given; ranges must be separated by commas. There must be no space between the -r and its argument. If no range is provided, the latest revision on the default branch, normally the trunk, is used. The possible values for revisions are the same as for log (see log).

-R

Display the name of the repository copy of the file only.

-s states

Display only revisions with states that match one of the states in the comma-separated list.

-S

Do not display header information of a file if there are no revisions to display.

-t

Print only the header information of a file and its description, not the log messages or revision information.

-w[usernames]

Display only revisions committed by the usernames in the comma-separated list. If there are no usernames listed, the revisions committed by the current user are displayed. There can be no space between -w and its argument.

rtag
cvs [cvs-options] rtag [options] tagname files ...

Mark a revision of a single file with a meaningful name, or mark a set of revisions of multiple files so that they can all be retrieved easily as a group. Tagnames must begin with a letter and may contain only alphanumeric characters, underscores (_), and hyphens (-). There are two tags reserved for CVS: the BASE and HEAD tags. See also tag.

The tag and rtag commands are also used to create branches.

The rtag command does not need to run from a sandbox, but it does need to have a revision or date specified. It also requires a filename, directory name, or module name given as a parameter.

Synonyms: rt, rfreeze

Standard subcommand options: -D, -f, -l, -n, -r, -R

Options

-a

Clear a tag from files that have been removed from active development. Normally, removed files are not searched when tags are removed. This option works with the -d and -F options.

-b

Create a branch off the designated revision (provided with -r), using the designated tagname as the branch name.

-B

Allow -F and -d to act on branch tags. Back up the repository before you use this option, and be extremely careful. See Chapter 4 in Essential CVS (O'Reilly) before using this option.

-d

Delete the specified tag.

-F

Move the tag from the revision it currently refers to, to the revision specified in the rtag command.

Examples

$ cvs -d cvs:/var/lib/cvs rtag -D now alpha_1-6 wizzard
cvs rtag: Tagging wizzard
cvs rtag: Tagging wizzard/doc
cvs rtag: Tagging wizzard/doc/design
cvs rtag: Tagging wizzard/doc/plan
...

server
cvs server

Runs the repository end of the CVS server using an internal version of the rsh program. The CVS client must also be able to use this internal version. This is used for the server access method. See also kserver and pserver.

Synonyms: none

status
cvs [cvs-options] status [-vlR] [files ...]

Display information about files, such as the current working or base revision, the current revision in the repository, and whether the files are currently synchronized with the repository. With the -v option, status also shows the files' tags.

Synonyms: st, stat

Standard subcommand options: -l, -R

Options

-v

Include information about tags.

Examples

$ cvs status Makefile
=  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==
File: Makefile                              Status: Locally Modified

Working revision:    1.6
Repository revision: 1.6     /var/lib/cvs/wizzard/Makefile,v
Sticky Tag:          (none)
Sticky Date:         (none)
Sticky Options:      (none)

tag
cvs [cvs-options] tag [options]\ tagname [files ...]

Mark a revision of a single file with a meaningful name, or mark a set of revisions of multiple files so that they can all be retrieved easily as a group. Tagnames must begin with a letter and may contain only alphanumeric characters, underscores (_), and hyphens (-). There are two tags reserved for CVS: the BASE and HEAD tags. See also rtag.

The tag and rtag commands are also used to create branches.

If no revision number or date is given to the tag command, this command tags based on the most recent revision in the repository that was synchronized with the current sandbox directory (i.e., the most recently updated, checked-out, or committed revision). This revision can be seen as the working revision in the cvs status command.

Synonyms: ta, freeze

Standard subcommand options: -D, -f, -l, -r, -R

Options

-b

Create a branch off the specified revision, using the specified tagname as the branch name.

-c

Check whether the sandbox copies of the specified files have been modified since they were last synchronized with the repository. If they have been modified, do not tag them and display an error. If they are unmodified, tag them with the specified tagname. This option is useful when tagging the current sandbox revisions.

-d

Delete the specified tagname from a file.

-F

Move the tagname from the revision it currently refers to, to the revision specified in the tag command.

Examples

$ cvs tag alpha_1-5
cvs server: Tagging .
T Changelog
T INSTALL
T Makefile
T README
T TODO
...

unedit
cvs [cvs-options] unedit [-lR] [files ...]

Unmark a file as being edited by the current user. The cvs unedit command is used as part of the cvs watch family of commands. If a file is being watched, CVS writes it (when it is checked out) to the sandbox with read permissions but not write permissions. The unedit command notifies watchers that the file is no longer being edited, clears the temporary watch, sets the file as read-only, and restores the file to the repository revision that the sandbox copy was based on. See also edit, editors, watch, and watchers.

The script in the notify file in the repository's CVSROOT directory is used to notify the user of changes.

Synonyms: none

Standard subcommand options: -l, -R

update
cvs [cvs-options] update [options] [files ...]

Download changes from the repository to an existing sandbox. While doing this, update merges changes from the repository into changed files in the sandbox. See also checkout and export.

If update cannot merge repository changes with sandbox changes without losing data, it reports a conflict.

If update is not given any filenames or directory names as parameters, it acts on the current sandbox.

Synonyms: up, upd

Standard subcommand options: -D, -f, -k, -l, -r, -R

Options

-A

Clear sticky tags, dates, and keyword-expansion modes and replace the current files in the sandbox with the head of the trunk.

-C

Replace any file that has been changed locally with the revision from the repository that the local file was based on. The modified local file is saved as .#file.revision in its local sandbox directory.

-d

Create any directories that are in the repository but not in the sandbox. By default, update works only on the directories that are currently in the sandbox and ignores any new directories.

-I file

Ignore the named file when updating. -I can be used more than once. Use -I ! to clear the list of ignored files.

-j revision[:date]

Determine the changes between the revision the files in the sandbox are based on and the specified revision, and merge the changes to the sandbox.

If two -j options are used, determine the changes between the first -j revision and the second -j revision, and merge those changes to the sandbox.

The date can be used only if the revision designates a branch. If date is used, it specifies the latest revision on (not before) that date.

-p

Update the listed files, but write them to standard output rather than to the filesystem. Do not change the sandbox.

-P

Do not include empty directories in the sandbox.

-W wrapper

Modify the update based on elements of each filename.

Examples

$ cvs update
cvs server: Updating .
U wizzard/Changelog
U wizzard/INSTALL
U wizzard/Makefile

version
cvs [cvs-options] version

Display the version information for the current installation of CVS.

Synonyms: ve, ver

Examples

$ cvs version
Concurrent Versions System (CVS) 1.11.15 (client/server)

watch
cvs [cvs-options] watch command [options] [files ...]

Set files to be watched, or add users to the file-watch list. Users who are watching a file are notified via the script in the notify file in the repository's CVSROOT directory when other users perform specific actions. Essential CVS (O'Reilly) explains uses of the cvs watch family of commands. See also edit, editors, unedit, and watchers.

NOTE

CVS does not notify you of your own changes.

Synonyms: none

Standard subcommand options: -l, -R

Commands

on and off

The on and off subcommands control whether the file or files are marked as being watched. If a file is marked as being watched, CVS sets it as read-only when it is checked out of the repository. Without this read-only setting, developers might forget to use cvs edit when editing a file.

If the argument is a directory, all current files in the directory and all new files added to that directory in the future are set as being watched.

The on and off subcommands set whether a file is watchable, but they do not set who is watching it; the add and remove subcommands set whether or not you are watching a file.

add and remove

Use the add and remove subcommands to set or remove files you want to watch. Use the -a option to specify which actions you want to be notified of.

Options

-a action

Notify the user when the designated actions occur to the file. Each -a designates one possible action. The -a option can be repeated to designate multiple actions. The -a option is usable only with the add and remove subcommands.

These are the possible actions:

commit

Notify the user when someone else commits changes to the file.

edit

Notify the user if someone else has run cvs edit on the file.

unedit

Notify the user when the file is no longer being edited by someone else. Notification occurs when cvs unedit or cvs release runs, or when the file is deleted and re-created with cvs update or cvs checkout.

all

Notify the user in all of the previous cases.

none

Notify the user in none of the previous cases.

Example

$ cvs watch on Makefile         Enable watching
$ cvs watch add Makefile        Add me to list of watchers

watchers
    cvs [cvs-options] watchers [-lR] [files ...]

Display the list of users who are watching the files listed as parameters. If no files are listed, this command lists the watchers for the files in the current directory and its subdirectories. See also edit, editors, unedit, and watch.

Standard subcommand options: -l, -R

Examples

$ cvs watchers Makefile
Makefile doppel edit unedit commit
arnold edit unedit commit


Chapter 14. The Subversion Version Control System

The Subversion version control system is a powerful, open source system for management of file and directory versions. Designed from the ground up to support distributed development, it offers many leading-edge features.

This chapter covers the following topics:

  • Conceptual overview

  • Obtaining Subversion

  • Using Subversion: a quick tour

  • The Subversion command line client: svn

  • Repository administration: svnadmin

  • Examining the repository: svnlook

  • Providing remote access: svnserve

  • Other Subversion components

Version control was introduced in Chapter 12, which contained a comparison of Subversion, CVS, and other popular systems. Most of the material in the current chapter is adapted from Version Control with Subversion (O'Reilly). See that book for much more information on Subversion.


Section 14.1. Conceptual Overview

14.1. Conceptual Overview

Subversion is a version-control system. It lets you track changes to an entire project directory tree. Every change made to the tree is recorded and can be retrieved.

Subversion is intended to be "a better CVS"; this is discussed in detail shortly. Subversion is purposely an open source project. If you want to participate, you can!

14.1.1. Basic Version-Control Operations

Actual data is kept in a repository, a set of directories and files managed by Subversion. Users use the svn client program to access the repository and make changes to it.

Subversion uses the copy-modify-merge development model. You make a private copy of a given project in a sandbox. (This is often called checking out a copy.) Like CVS, this private copy is not locked in the repository. You then make all the changes you like to the copy within the sandbox, without having to worry about what other developers are doing. As you work, you can compare your changes to the version you started with, as well as the version currently in the repository. Once you're satisfied with the changes, you commit them, sometimes referred to as a check-in. (These terms come from RCS and CVS.)

In the event that another developer has modified part of a file that you were working on and checked it in, when you commit your changes, Subversion notices and indicates that a conflict exists. Conflicts are marked as such in the file, and Subversion creates pristine copies of the file as it exists in the repository and of the file as you modified it, so that you can do full comparisons. Once you have resolved the conflict, you tell Subversion about it, and then commit the final version.

Like CVS, Subversion lets you create a development branch, a separate stream of development versions. You can periodically merge changes from the main development stream (the trunk) into your branch, and also merge changes from your branch back into the trunk.

Finally, you can tag a particular copy of the project. For instance, when a project is ready for a release, you can create a snapshot of the project and give it a descriptive tag that allows you to re-create the project tree exactly as it was for the release. This is particularly valuable when you need to produce a bug fix for an older version of the project, or when you have to attempt to retrofit a fix or feature from current development into an older version.

14.1.2. Building a Better CVS

When discussing Subversion's features, it is often helpful to speak of them in terms of how they improve upon CVS's design. Subversion provides:

Directory versioning

CVS only tracks the history of individual files, but Subversion implements a virtual versioned filesystem that tracks changes to whole directory trees over time. Files and directories are versioned.

True version history

Since CVS is limited to file versioning, operations such as copies and renameswhich might happen to files, but which are really changes to the contents of some containing directoryaren't supported in CVS. In CVS, you cannot delete a versioned file and then create a new file of the same name with different contents without inheriting the history of the oldperhaps completely unrelatedfile. With Subversion, you can add, delete, copy, and rename both files and directories. And every newly added file begins with a fresh, clean history all its own, even if the filename was previously used.

Atomic commits

A collection of modifications either goes into the repository completely, or not at all. This allows developers to construct and commit changes as logical chunks, and prevents problems that can occur when only a portion of a set of changes is successfully sent to the repository.

Versioned metadata

Each file and directory has a set of propertieskeys and their valuesassociated with it. You can create and store any arbitrary key/value pairs. Properties are versioned over time, just like file contents.

Choice of network layers

Subversion has an abstracted notion of repository access, making it easy for people to implement new network mechanisms. Subversion can plug into the Apache HTTP Server as an extension module. This gives Subversion a big advantage in stability and interoperability, and instant access to existing features provided by that serverauthentication, authorization, wire compression, and so on. A more lightweight, standalone Subversion server process is also available. This server speaks a custom protocol that can be easily tunneled over SSH.

Consistent data handling

Subversion expresses file differences using a binary differencing algorithm, which works identically on both text (human-readable) and binary (human-unreadable) files. Both types of files are stored equally compressed in the repository, and only the differences are transmitted in both directions across the network.

Efficient branching and tagging

The cost of branching and tagging need not be proportional to the project size. Subversion creates branches and tags by simply copying the project, using a mechanism similar to a hard link. Thus these operations take only a very small, constant amount of time.

Hackability

Subversion has no historical baggage; it is implemented as a collection of shared C libraries with well-defined APIs. This makes Subversion extremely maintainable and usable by other applications and languages.

Optimized around the network

Disk storage continues to increase in size and speed, and decrease in cost: disk space is cheap on today's systems. However, network connectivity has not kept pace; access to remote repositories is several orders of magnitude slower than local access. Thus the Subversion design is optimized to avoid connecting to the repository when possible. For example, in the working copy's administrative directory, .svn, Subversion maintains a pristine copy of each file as it was checked out of the repository. This makes it possible to produce the differences very quickly, with no need to contact the repository.

In addition, Subversion uses similar commands to those of CVS, making it straightforward to transfer your CVS habits to Subversion.

14.1.3. Converting a Repository from CVS to Subversion

A very effective way to learn Subversion if you already know CVS is to move your project from CVS to Subversion. The minimal way to accomplish this is to do a flat import into a Subversion repository from an exported CVS repository. However, this only gives you a "snapshot" of your repository; the revision history (changes, logs, tags, branches, etc.) are not kept.

Copying a repository while maintaining history is a difficult problem to solve. Nevertheless, a few tools exist that at least partially convert existing CVS repositories into new Subversion ones, such as cvs2svn, a Python script originally created by members of Subversion's own development community (see http://cvs2svn.tigris.org/), and Lev Serebryakov's RefineCVS (see http://lev.serebryakov.spb.ru/refinecvs/).

For an updated collection of links to known converter tools, visit the Links page of the Subversion web site (http://subversion.tigris.org/project_links.html).

14.1.4. Special File Properties

Subversion allows you to associate properties with files or directories. A property is just a keyword/value pair associated with the file. Subversion reserves property names starting with svn: for its own use. The special properties in Subversion 1.0 are:

svn:author

The username of the person who committed a particular revision.

svn:date

The date when the transaction for a revision was created.

svn:eol-style

Different operating systems use different conventions to mark the end of lines in text files. Unix and its workalikes use a single ASCII line-feed character (LF) to end lines. MS Windows systems use a Carriage Return + Line Feed combination (CRLF), and older Macintosh systems use a single Carriage Return (CR). This can cause problems when a Windows user stores a new revision of the file: suddenly a Unix user who does a checkout sees a file with extraneous Carriage Return characters at the end of every line. The svn:eol-style attribute solves this problem. It should be set to one of the following values:

CR

Clients should always use CR line terminators, no matter what the native format is.

CRLF

Clients should always use CR-LF line terminators, no matter what the native format is.

LF

Clients should always use LF line terminators, no matter what the native format is.

native

Clients should use the native format when checking out files.

Subversion always stores files in normalized, LF-only format in the repository.

svn:executable

Valid only for files, the mere presence of this property indicates that the file should be made executable when it's checked out or updated from the repository. It has no effect on filesystems, such as FAT-32 or NTFS, that don't have the concept of an execute bit.

svn:externals

This property, when set on a directory under version control, allows you to specify other, external repositories to use for particular local subdirectories. You set this property with svn propset or svn propedit (see svn Subcommands," later in this chapter). The value is a multiline table of directories and fully qualified Subversion URLs. For example:

    $ svn propget svn:externals calc
    third-party/sounds             http://sounds.red-bean.com/repos
    third-party/skins              http://skins.red-bean.com/repositories/
    skinproj
    third-party/skins/toolkit -r21 http://svn.red-bean.com/repos/skin-maker

Once set, anyone else who checks out a working copy will also get the third party files checked out automatically.

svn:ignore

A property containing a list of file patterns that certain Subversion operations will ignore. It should be set on directories, as needed. It works to filter unversioned files and directories out of commands like svn status, svn add, and svn import. It is similar to the .cvsignore file in CVS, and you can often import your .cvsignore with this command:

    $ svn propset svn:ignore -F .cvsignore .
    property 'svn:ignore' set on '.'

svn:keywords

A list of keywords for which Subversion should perform keyword expansion when checking out the file. This is purposely similar to the same feature in RCS and CVS. However, Subversion does keyword expansion only when this property is set, and only for the keywords listed in the property's value. The list of recognized keywords is provided shortly.

svn:log

The log message associated with the commit of a particular revision.

svn:mime-type

An indication of the type of data stored in the file. In general, if it does not begin with text/, Subversion assumes that the file contains binary data. For updates, this causes Subversion to rename a modified working copy of the file with a .orig extension and replace the file with the current version from the repository. This prevents an attempt to perform a "merge" on data that can't be merged. This property also influences how the Subversion Apache module sets the HTTP Content-type: header.

svn:realmstring

A specialized property that describes the "authentication realm" for a file in Subversion's cached copy of the authentication credentials. See Chapter 6 of Version Control with Subversion (O'Reilly) for more information.

Subversion defines the list of keywords available for substitution. That list contains the following five keywords, some of which have shorter aliases that you can also use:

$LastChangedDate$

This keyword describes the last time the file was changed in the repository and looks like $LastChangedDate: 2002-07-22 21:42:37 -0700 (Mon, 22 Jul 2002) $. It may be abbreviated as Date.

$LastChangedRevision$

This keyword describes the last revision in which this file changed in the repository and looks like $LastChangedRevision: 144 $. It may be abbreviated as Revision or Rev.

$LastChangedBy$

This keyword describes the last user to change this file in the repository, and looks like $LastChangedBy: harry $. It may be abbreviated as Author.

$HeadURL$

This keyword describes the full URL to the latest version of the file in the repository. It looks like $HeadURL: http://svn.collab.net/repos/trunk/README $. It may be abbreviated as URL.

$Id: ch14.xml,v 1.5 2005/08/12 21:21:32 sally Exp sally $

This keyword is a compressed combination of the other keywords. Its substitution looks like $Id: ch14.xml,v 1.5 2005/08/12 21:21:32 sally Exp sally $, and is interpreted to mean that the file calc.c was last changed in revision 148 on the evening of July 28, 2005 by the user sally.


Section 14.2. Obtaining Subversion

14.2. Obtaining Subversion

The Subversion project web site is http://subversion.tigris.org. It contains links to project documentation, Frequently Asked Questions (FAQs), and project source code.

Some GNU/Linux systems come with Subversion available on the installation CDs. Thus, you may be able to install a prebuilt binary for your system or use a package manager to download and install it.

14.2.1. Subversion Releases

Subversion uses the "even / odd" release model. Even numbered point releases (1.0, 1.2, etc.) are considered to be stable releases. Such releases undergo change only to fix problems. New features are not added, and users can expect to use the software without problems. Odd numbered point releases (1.1, 1.3, etc.), on the other hand, are development versions. New features are added in such versions, they tend to undergo rapid change and evolution, and such releases may have bugs or problems that could cause loss of data. You should use an even-numbered release if stability and data preservation are important to you. Use an odd-numbered release only if it has a critical, must-have feature and if you are willing to live with the risks involved.

14.2.2. A View Down The Road

The one constant in the open source world is change. At the time of writing, Subversion 1.0 is the current released stable version. The first development release of Subversion 1.1 is also available. Along with a host of fixes and several new command-line options, the next version has the following interesting features:

Symbolic links may be versioned

Unix-style symbolic links are stored in the repository as a regular file with a special attribute. The svn client knows how to store and extract symbolic links correctly on Unix-style systems.

Nondatabase repository backend

Repositories can be set up to store data in regular files, instead of requiring the use of Berkeley DB.

Better localization support

The framework for localization of the Subversion code has been improved, with at least eight translations already available.

The Subversion web site's Roadmap page (http://subversion.tigris.org/roadmap.html ) lists the following future development goals. (You should recheck the website, things will undoubtedly have changed.)

Subversion 1.2 goals

  • Optional locking (reserved checkouts).

Medium-term goals

  • True rename support (not based on copy/delete).

  • Merge tracking (describes a whole class of problems).

  • Repository-level Access Control Lists (ACLs).[*]

    [*] ACLs provide finer-grained access controls than the regular Unix user/group/other permissions mechanism. Many Unix systems support some form of ACLs, but in incompatible ways.

Long-term goals

  • SQL repository backend.

  • Rewrite of working-copy library.

  • Broader WebDAV/DeltaV compatibility.[ [image]]

    [ [image]] WebDAV is short for "Web-based Distributed Authoring and Versioning," an extension to HTTP that makes read/write file resources available over the Web. Despite the "V" in the name, the original specification (RFC 2518) does not provide a model for version control, Such a model is provided by DeltaV, described in RFC 3253. See http://www.webdav.org for more information.

  • Pluggable client-side diff programs.

  • Progressive multilingual support.

14.2.3. Source Code

The latest Subversion source is kept in a Subversion archive available from the main Subversion site. This leads to a so-called bootstrapping problem; you can't get Subversion unless you already have it. Fortunately, the developers make Subversion releases available as standalone tar archives, which you can use to build your initial Subversion client. You can get these from the main web site, http://subversion.tigris.org. Once there, select the "Downloads" link. You may choose to download a binary distribution (Red Hat RPM file, Debian package, etc.), if one is available. This is the easiest road to take. Or you may choose to download source code and build your own.


Section 14.3. Using Subversion: A Quick Tour

14.3. Using Subversion: A Quick Tour

This section provides a very quick tour of using Subversion for version control. We start with the initial version of a project for importing into Subversion:

    $ find /tmp/hello -print                    Show directory layout
    /tmp/hello
    /tmp/hello/branches                        Directory for branch development
    /tmp/hello/tags                            Directory for tagged releases
    /tmp/hello/trunk
    /tmp/hello/trunk/hello.c                   Mainline development is done on the trunk
    /tmp/hello/trunk/Makefile
    /tmp/hello/trunk/README

The next steps are to create the repository and then to import the project into it:

    $ svnadmin create /path/to/svnrepos
    $ svn import /tmp/hello file:///path/to/svnrepos -m "initial import"
    Adding         /tmp/hello/trunk
    Adding         /tmp/hello/trunk/hello.c
    Adding         /tmp/hello/trunk/Makefile
    Adding         /tmp/hello/trunk/README
    Adding         /tmp/hello/branches
    Adding         /tmp/hello/tags

    Committed revision 1.

Now that the project exists in Subversion, we check out a working copy into a sandbox underneath our home directory and start making changes:

    $ cd                                             Move to home directory
    $ svn checkout file:///path/to/svnrepos hello    Check out working copy
    A  hello/trunk
    A  hello/trunk/hello.c
    A  hello/trunk/README
    A  hello/trunk/Makefile
    A  hello/branches
    A  hello/tags
    Checked out revision 1.

    $ cd hello/trunk                                 Change to sandbox
    $ vi message.c hello.c Makefile                  Make changes
    3 files to edit

    $ cat message.c                                  Show newly created file
    const char message[  ] = "hello, world!";
    $ make                                           Compile program and test it
    cc    -c -o hello.o hello.c
    cc    -c -o message.o message.c
    cc -O hello.o message.o -o hello
    $ hello
    hello, world!

One of the most common operations is to compare the changed copy with the original. The result is in unified diff format, the equivalent of the regular diff -u command:

    $ svn diff hello.c
    Index: hello.c
    ===============================================================
    ====
    --- hello.c     (revision 1)
    +++ hello.c     (working copy)
    @@ -1,7 +1,9 @@
     #include <stdio.h>

    +extern const char message[  ];
    +
     int main(void)
     {
    -       printf("hello, world!\n");
    +       printf("%s\n", message);
            return 0;
     }

Now that we're comfortable with the changes, we schedule the new file, message.c, for addition to the repository, and then we actually commit our changes:

    $ svn add message.c                              Schedule message.c for addition
    A         message.c
    $ svn commit                                     Commit all the changes
    Sending        trunk/Makefile
    Sending        trunk/hello.c
    Adding         trunk/message.c
    Transmitting file data ...
    Committed revision 2.

Finally, we can view all our changes relative to the initial revision:

    $ svn diff -r 1
    Index: hello.c
    ===================================================================
    --- hello.c     (revision 1)
    +++ hello.c     (working copy)
    @@ -1,7 +1,9 @@
     #include <stdio.h>

    +extern const char message[  ];
    +
     int main(void)
     {
    -       printf("hello, world!\n");
    +       printf("%s\n", message);
            return 0;
     }
    Index: Makefile
    =================================================================
    ==
    --- Makefile    (revision 1)
    +++ Makefile    (working copy)
    @@ -1,2 +1,2 @@
    -hello: hello.c
    -       $(CC) -O $< -o $@
    +hello: hello.o message.o
    +       $(CC) -O hello.o message.o -o $@
    Index: message.c
    =================================================================
    ==
    --- message.c   (revision 0)
    +++ message.c   (revision 2)
    @@ -0,0 +1 @@
    +const char message[  ] = "hello, world!";


Section 14.4. The Subversion Command Line Client: svn

14.4. The Subversion Command Line Client: svn

The syntax for the Subversion command line client, svn, is:

The options and subcommand may be provided in any order.

14.4.1. svn Options

While Subversion has different options for its subcommands, all options are globalthat is, each option is guaranteed to mean the same thing regardless of the subcommand you use it with. For example, --verbose (-v) always means verbose output, regardless of the subcommand you use it with.

--auto-props

Enable auto-props, overriding the enable-auto-props directive in the config file.

--config-dir dir

Read configuration information from the specified directory instead of the default location (.subversion in the user's home directory).

--diff-cmd cmd

Use cmd as the external program to show differences between files. By default, svn diff uses Subversion's internal diff engine, which provides unified diffs by default. To use an external diff program, use --diff-cmd. You can pass options to the diff program with the --extensions option (discussed later in this list).

--diff3-cmd cmd

Use cmd as the external program to merge files.

--dry-run

Pretend to run a command, but make no actual changeseither on disk or in the repository.

--editor-cmd cmd

Use cmd as the program for editing a log message or a property value. If not set, Subversion checks the environment variables SVN_EDITOR, VISUAL, and EDITOR, in that order, for the name of the editor to use.

--encoding enc

Use enc as the encoding for the commit message. The default encoding is your operating system's native locale, and you should specify the encoding if your commit message is in any other encoding.

--extensions args, -x args

Pass args to an external diff command when providing differences between files. To pass multiple arguments, enclose all of them in quotes (for example, svn diff --diff-cmd /usr/bin/diff -x "-b -E"). This option can be used only if you also pass the --diff-cmd option.

--file filename, -F filename

Use the contents of filename for the specified subcommand.

--force

Force a particular command or operation to run. There are some operations that Subversion prevents you from doing in normal usage, but you can pass this option to tell Subversion that you know what you're doing, as well as the possible repercussions of doing it, so do it anyway. Use with caution.

--force-log

Force a suspicious parameter passed to the --message (-m) or --file (-F) options to be accepted as valid. By default, Subversion produces an error if parameters to these options look like they might instead be targets of the subcommand. For example, if you pass a versioned file's path to the --file (-F) option, Subversion assumes you've made a mistake, that the path was instead intended as the target of the operation, and that you simply failed to provide some otherunversioned--file as the source of your log message. To assert your intent and override these types of errors, pass the --force-log option to commands that accept log messages.

--help, -h, -?

If used with one or more subcommands, show the built-in help text for each subcommand. If used alone, display the general client help text.

--ignore-ancestry

Ignore ancestry when calculating differences (i.e., rely on path contents alone).

--incremental

Print output in a format suitable for concatenation.

--message message, -m message

Use message as the commit message. For example:

    $ svn commit -m "They don't make Sunday."

--new arg

Use arg as the newer target when producing a diff.

--no-auth-cache

Do not cache authentication information (e.g., username and password) in the Subversion administrative directories.

--no-auto-props

Disable auto-props, overriding the enable-auto-props directive in the config file.

--no-diff-deleted

Do not print differences for deleted files. The default behavior when you remove a file is for svn diff to print the same differences that you would see if you had left the file but removed all the content.

--no-ignore

Show files in the status listing that would normally be omitted because they match a pattern in the svn:ignore property.

--non-interactive

In the case of an authentication failure, or insufficient credentials, do not prompt for credentials (e.g., username or password). This is useful if you're running Subversion inside of an automated script where it's better to have Subversion fail instead of trying to prompt for more information.

--non-recursive, -N

Stop a subcommand from recursing into subdirectories. Most subcommands recurse by default, but some subcommandsusually those that have the potential to remove or undo your local modificationsdo not.

--notice-ancestry

Pay attention to ancestry when calculating differences.

--old arg

Use arg as the older target when producing a diff.

--password pass

Use pass as the password for authentication on the command line; otherwise, if it is needed, Subversion prompts you for it.

--quiet, -q

Print only essential information while performing an operation.

--recursive, -R

Make a subcommand recurse into subdirectories. Most subcommands recurse by default.

--relocate from to [path ...]

Used with the svn switch subcommand to change the location of the repository that your working copy references. This is useful if the location of your repository changes and you have an existing working copy that you'd like to continue to use. See svn switch in the svn Subcommands section, later in this chapter, for an example.

--revision rev, -r rev

Use rev as the revision (or range of revisions) for a particular operation. You can provide revision numbers, revision keywords, or dates (in curly braces) as arguments to the revision option. To provide a range of revisions, provide two revisions separated by a colon. For example:

    $ svn log -r 1729
    $ svn log -r 1729:HEAD
    $ svn log -r 1729:1744
    $ svn log -r {2001-12-04}:{2002-02-17}
    $ svn log -r 1729:{2002-02-17}

The acceptable revision keywords for --revision are:

BASE

The original, unmodified version of the working copy. This keyword cannot refer to a URL.

COMMITTED

The last revision, before or at BASE, at which an item actually changed. This keyword cannot refer to a URL.

HEAD

The most recent revision in the repository.

PREV

The revision just before that at which an item changed. Equivalent to COMMITED - 1. This keyword cannot refer to a URL.

Revision Date

A date specification enclosed in curly braces, { and }, such as {2002-02-17}, {15:30}, {"2002-02-17 15:30"}, {2002-02-17T15:30}, or {20020217T1530-0500}. See Version Control with Subversion (O'Reilly) for full details.

--revprop

Operate on a revision property instead of a Subversion property specific to a file or directory. This option requires that you also pass a revision with the --revision (-r) option.

--show-updates, -u

Display information about which files in your working copy are out of date. This doesn't actually update any of your files; it just shows you which files will be updated if you run svn update.

--stop-on-copy

Cause a Subversion subcommand that is traversing the history of a versioned resource to stop harvesting that historical information when it encounters a copythat is, a location in history where that resource was copied from another location in the repository.

--strict

Use strict semantics, a notion that is rather vague unless talking about specific subcommands. See Version Control with Subversion (O'Reilly) for more information.

--targets filename

Retrieve the list of files to operate on from filename instead of listing all the files on the command line.

--username name

Use name as the username for authentication; otherwise, if it is needed, Subversion prompts you for it.

--verbose, -v

Print out as much information as possible while running any subcommand. This may result in Subversion printing out additional fields, detailed information about every file, or additional information regarding its actions.

--version

Print the client version info. This information not only includes the version number of the client, but also a listing of all repository access modules that the client can use to access a Subversion repository.

--xml

Prints output in XML format.

14.4.2. svn Subcommands

The svn command is the main user interface to Subversion. It works by accepting subcommands with arguments. The general form is:

svn subcommand[options] arguments
add
svn add path ...

Add files and directories to your working copy and schedule them for addition to the repository. They will be uploaded and added to the repository on your next commit. If you add something and change your mind before committing, you can unschedule the addition using svn revert.

Alternate names: none

Changes: working copy

Accesses repository: no

Options

--auto-props
--config-dir dir
--no-auto-props
--non-recursive (-N)
--quiet (-q)
--targets filename

Examples

To add a file to your working copy:

    $ svn add foo.c
    A         foo.c

You can add a directory without adding its contents:

    $ svn add --non-recursive otherdir
    A         otherdir

blame
svn blame target ...

Show author and revision information inline for the specified files or URLs. Each line of text is annotated at the beginning with the author (username) and the revision number for the last change to that line.

Alternate names: praise, annotate, ann

Changes: nothing

Accesses repository: yes

Options

--config-dir dir
--no-auth-cache
--non-interactive
--password pass
--revision rev, -r rev
--username user
cat
    svn cat target ...

Output the contents of the specified files or URLs. For listing the contents of directories, see svn list.

Alternate names: none

Changes: nothing

Accesses repository: yes

Options

--config-dir dir
--no-auth-cache
--non-interactive
--password pass
--revision rev, -r rev
--username user

Examples

To view readme.txt in your repository without checking it out:

    $ svn cat http://svn.red-bean.com/repos/test/readme.txt
    This is a README file.
    You should read this.

NOTE

If your working copy is out of date (or if you have local modifications) and you want to see the HEAD revision of a file in your working copy, svn cat automatically fetches the HEAD revision when you give it a path:

    $ cat foo.c
    This file is in my local working copy
    and has changes that I've made.

    $ svn cat foo.c
    Latest revision fresh from the repository!

checkout
    svn checkout URL ... [path]

Check out a working copy from a repository. If path is omitted, the basename of the URL is used as the destination. If multiple URLs are given, each one is checked out into a subdirectory of path, with the name of the subdirectory being the basename of the URL.

Alternate names: co

Changes: creates a working copy

Accesses repository: yes

Options

--config-dir dir
--no-auth-cache
--non-interactive
--non-recursive (-N)
--password pass
--quiet (-q)
--revision rev, -r rev
--username user

Examples

Check out a working copy into a directory called mine:

    $ svn checkout file:///tmp/repos/test mine
    A  mine/a
    A  mine/b
    Checked out revision 2.
    $ ls
    mine

If you interrupt a checkout (or something else interrupts your checkout, such as loss of connectivity, etc.), you can restart it either by issuing the identical checkout command again or by updating the incomplete working copy:

    $ svn checkout file:///tmp/repos/test test
    A  test/a
    A  test/b
    ^C
    svn: The operation was interrupted
    svn: caught SIGINT

    $ svn checkout file:///tmp/repos/test test
    A  test/c
    A  test/d
    ^C
    svn: The operation was interrupted
    svn: caught SIGINT

    $ cd test
    $ svn update
    A  test/e
    A  test/f
    Updated to revision 3.

cleanup
    svn cleanup [path ...]

Recursively clean up the working copy, removing locks and resuming unfinished operations. If you ever get a working-copy-locked error, run this command to remove stale locks and get your working copy into a usable state again.

If, for some reason, an svn update fails due to a problem running an external diff program (e.g., user input or network failure), pass the --diff3-cmd option to allow cleanup to complete any merging with your external diff program. You can also specify any configuration directory with the --config-dir option, but you should need these options extremely infrequently.

Alternate names: none

Changes: working copy

Accesses repository: no

Options:

--config-dir dir
--diff3-cmd cmd
commit
    svn commit [path ...]

Send changes from your working copy to the repository. If you do not supply a log message with your commit by using either the --file or --message option, svn starts your editor for you to compose a commit message.

NOTE

If you begin a commit and Subversion starts your editor to compose the commit message, you can still abort without committing your changes. To cancel your commit, just quit your editor without saving your commit message and Subversion prompts you to abort the commit, continue with no message, or edit the message again.

Alternate names: ci (short for check innot co, which is short for checkout)

Changes: working copy, repository

Accesses repository: yes

Options

--config-dir dir
--encoding enc
--file file, -F file
--force-log
--message text, -m text
--no-auth-cache
--non-interactive
--non-recursive (-N)
--password pass
--quiet (-q)
--targets filename
--username user

Examples

Commit a simple modification to a file with the commit message on the command line and an implicit target of your current directory (.):

    $ svn commit -m "added howto section."
    Sending        a
    Transmitting file data .
    Committed revision 3.

To commit a file scheduled for deletion:

    $ svn commit -m "removed file 'c'."
    Deleting       c
    Committed revision 7.

copy
    svn copy src dst

Copy a file in a working copy or in the repository. src and dst can each be either a working-copy (WC) path or a URL:

WC [image] WC

Copy and schedule an item for addition (with history).

WC [image] URL

Immediately commit a copy of WC to URL.

URL [image] WC

Check out URL into WC, and schedule it for addition.

URL [image] URL

Complete server-side copy. This is usually used to branch and tag.

NOTE

You can only copy files within a single repository. Subversion does not support cross-repository copying.

Alternate names: cp

Changes: repository if destination is a URL; working copy if destination is a WC path

Accesses repository: if source or destination is in the repository, or if needed to look up the source revision number

Options

--config-dir dir
--editor-cmd editor
--encoding enc
--file file, -F file
--force-log
--message text, -m text
--no-auth-cache
--non-interactive
--password pass
--quiet (-q)
--revision rev, -r rev
--username user

Examples

Copy an item within your working copy (just schedules the copy; nothing goes into the repository until you commit):

    $ svn copy foo.txt bar.txt
    A         bar.txt
    $ svn status
    A  +   bar.txt

Copy an item from the repository to your working copy (just schedules the copy; nothing goes into the repository until you commit):

NOTE

This is the recommended way to resurrect a dead file in your repository!

    $ svn copy file:///tmp/repos/test/far-away near-here
    A         near-here

And finally, copying between two URLs:

    $ svn copy file:///tmp/repos/test/far-away \
    > file:///tmp/repos/test/over-there -m "remote copy."
    Committed revision 9.

NOTE

This is the easiest way to tag a revision in your repository; just svn copy that revision (usually HEAD) into your tags directory.

    $ svn copy file:///tmp/repos/test/trunk \
    >          file:///tmp/repos/test/tags/0.6.32-prerelease \
    >          -m "tag tree"
    Committed revision 12.

delete
    svn delete path ...
    svn delete URL ...

Items specified by path are scheduled for deletion upon the next commit. Files (and directories that have not been committed) are immediately removed from the working copy. The command will not remove any unversioned or modified items; use the --force option to override this behavior.

Items specified by URL are deleted from the repository via an immediate commit. Multiple URLs are committed atomically.

Alternate names: del, remove, rm

Changes: working copy if operating on files; repository if operating on URLs

Accesses repository: only if operating on URLs

Options

--config-dir dir
--editor-cmd editor
--encoding enc
--file file, -F file
--force-log
--force
--message text, -m text
--no-auth-cache
--non-interactive
--password pass
--quiet (-q)
--targets filename
--username user
diff
    svn diff [-r N[:M]] [--old old-tgt] [--new new-tgt] [path ...]
    svn diff -r N:M URL
    svn diff [-r N[:M]] URL1[@N] URL2[@M]

Display the differences between two paths. The three different ways you can use svn diff are:

svn diff [-r N[:M]] [--old old-tgt] [--new new-tgt] [path ...]

Display the differences between old-tgt and new-tgt. If paths are given, they are treated as relative to old-tgt and new-tgt, and the output is restricted to differences in only those paths. old-tgt and new-tgt may be working copy paths or URL[@rev]. old-tgt defaults to the current working directory, and new-tgt defaults to old-tgt. N defaults to BASE or, if old-tgt is a URL, to HEAD. M defaults to the current working version or, if new-tgt is a URL, to HEAD. svn diff -r N sets the revision of old-tgt to N, whereas svn diff -r N:M also sets the revision of new-tgt to M.

svn diff -r N:M URL

A shorthand for svn diff -r N:M --old=URL --new=URL.

svn diff [-r N[:M]] URL1[@N] URL2[@M]

A shorthand for svn diff [-r N[:M]] --old=URL1 --new=URL2.

If target is a URL, then revisions N and M can be given either via the --revision option or by using @ notation as described earlier.

If target is a working copy path, then the --revision option means:

--revision N:M

The server compares target@N and target@M.

--revision N

The client compares target@N against the working copy.

No --revision option

The client compares the base and working copies of target.

If the alternate syntax is used, the server compares URL1 and URL2 at revisions N and M respectively. If either N or M are omitted, a value of HEAD is assumed.

By default, svn diff ignores the ancestry of files and merely compares the contents of the two files being compared. If you use --notice-ancestry, the ancestry of the paths in question is taken into consideration when comparing revisions. (That is, if you run svn diff on two files with identical contents but different ancestry you will see the entire contents of the file as having been removed and added again.)

Alternate names: di

Changes: nothing

Accesses repository: for obtaining differences against anything but the BASE revision in your working copy

Options

--config-dir dir
--diff-cmd cmd
--extensions args, -x args
--new new-target
--no-auth-cache
--no-diff-deleted
--non-interactive
--non-recursive (-N)
--notice-ancestry
--old old-target
--password pass
--revision rev, -r rev
--username user

Examples

Compare BASE and your working copy:

    $ svn diff COMMITTERS
    Index: COMMITTERS
    =================================================
    ==================
    --- COMMITTERS  (revision 4404)
    +++ COMMITTERS  (working copy)
    ...

See how your working copy's modifications compare against an older revision:

    $ svn diff -r 3900 COMMITTERS
    Index: COMMITTERS
    =================================================
    ==================
    --- COMMITTERS  (revision 3900)
    +++ COMMITTERS  (working copy)
    ...

Use --diff-cmd cmd and -x to pass arguments directly to the external diff program:

    $ svn diff --diff-cmd /usr/bin/diff -x "-i -b" COMMITTERS
    Index: COMMITTERS
    =================================================
    ==================
    0a1,2
    > This is a test
    >

export
    svn export [-r rev] URL [path]
    svn export path1 path2

The first form exports a clean directory tree into path from the repository specified by URL, at revision rev if it is givenotherwise at HEAD. If path is omitted, the last component of the URL is used for the local directory name.

The second form exports a clean directory tree from the working copy specified by path1 into path2. All local changes are preserved, but files not under version control are not copied.

Alternate names: none

Changes: local disk

Accesses repository: only if exporting from a URL

Options

--config-dir dir
--force
--no-auth-cache
--non-interactive
--password pass
--quiet (-q)
--revision rev, -r rev
--username user
help
    svn help [subcommand ...]

Provide a quick usage summary. With subcommand, provide information about the given subcommand.

Alternate names: ?, h

Changes: nothing

Accesses repository: no

Options

--quiet (-q)
--version
import
    svn import [path] URL

Recursively commit a copy of path to URL. If path is omitted, . is assumed. Parent directories are created in the repository as necessary.

Alternate names: none

Changes: repository

Accesses repository: yes

Options

--auto-props
--config-dir dir
--editor-cmd editor
--encoding enc
--file file, -F file
--force-log
--message text, -m text
--no-auth-cache
--no-auto-props
--non-interactive
--non-recursive (-N)
--password pass
--quiet (-q)
--username user

Examples

Import the local directory myproj into the root of your repository:

    $ svn import -m "New import" myproj \
    > http://svn.red-bean.com/repos/test
    Adding         myproj/sample.txt
    ...
    Transmitting file data .........
    Committed revision 16.

Import the local directory myproj into trunk/vendors in your repository. The directory trunk/vendors need not exist before you import into it; svn import will recursively create directories for you:

    $ svn import -m "New import" myproj \
    > http://svn.red-bean.com/repos/test/trunk/vendors/myproj
    Adding         myproj/sample.txt
    ...
    Transmitting file data .........
    Committed revision 19.

After importing data, note that the original tree is not under version control. To start working, you still need to svn checkout a fresh working copy of the tree.

info
    svn info [path ...]

Print information about paths in your working copy, including:

  • Path

  • Name

  • URL

  • Revision

  • Node kind

  • Last changed author

  • Last changed revision

  • Last changed date

  • Text last updated

  • Properties last updated

  • Checksum

Alternate names: none

Changes: nothing

Accesses repository: no

Options

--config-dir dir
--recursive (-R)
--targets filename
list
    svn list [target ...]

List each target file and the contents of each target directory as they exist in the repository. If target is a working copy path, the corresponding repository URL is used. The default target is ., meaning the repository URL of the current working-copy directory.

With --verbose, the following fields show the status of the item:

  • Revision number of the last commit

  • Author of the last commit

  • Size (in bytes)

  • Date and time of the last commit

Alternate names: ls

Changes: nothing

Accesses repository: yes

Options

--config-dir dir
--no-auth-cache
--non-interactive
--password pass
--recursive (-R)
--revision rev, -r rev
--username user
--verbose (-v)

Examples

To see what files a repository has without downloading a working copy:

    $ svn list http://svn.red-bean.com/repos/test/support
    README.txt
    INSTALL
    examples/
    ...

Pass the --verbose option for additional information:

    $ svn list --verbose file:///tmp/repos
         16 sally         28361 Jan 16 23:18 README.txt
         27 sally             0 Jan 18 15:27 INSTALL
         24 harry               Jan 18 11:27 examples/

log
    svn log [path]
    svn log URL [path ...]

The default target is the path of your current directory. If no arguments are supplied, svn log shows the log messages for all files and directories inside of (and including) the current working directory of your working copy. You can refine the results by specifying a path, one or more revisions, or any combination of the two. The default revision range for a local path is BASE:1.

If you specify a URL alone, the command prints log messages for everything that the URL contains. If you add paths past the URL, only messages for those paths under that URL are printed. The default revision range for a URL is HEAD:1.

With --verbose, svn log also prints all affected paths with each log message. With --quiet, svn log does not print the log message body itself (this is compatible with --verbose).

Each log message is printed just once, even if more than one of the affected paths for that revision were explicitly requested. Logs follow copy history by default. Use --stop-on-copy to disable this behavior, which can be useful for determining branch points.

Alternate names: none

Changes: nothing

Accesses repository: yes

Options

--config-dir dir
--incremental
--no-auth-cache
--non-interactive
--password pass
--quiet (-q)
--revision rev, -r rev
--stop-on-copy
--targets filename
--username user
--verbose (-v)
--xml

Examples

To see the log messages for all the paths that changed in your working copy, run svn log from the top:

    $ svn log
    ------------------------------------------------------------------------
    r20 | harry | 2003-01-17 22:56:19 -0600 (Fri, 17 Jan 2003)
    | 1 line

    Tweak.
    ------------------------------------------------------------------------
    r17 | sally | 2003-01-16 23:21:19 -0600 (Thu, 16 Jan 2003)
    | 2 lines
    ...

If you don't have a working copy handy, you can log a URL:

    $ svn log http://svn.red-bean.com/repos/test/foo.c
    ------------------------------------------------------------------------
    r32 | sally | 2003-01-13 00:43:13 -0600 (Mon, 13 Jan 2003)
    | 1 line

    Added defines.
    ------------------------------------------------------------------------
    r28 | sally | 2003-01-07 21:48:33 -0600 (Tue, 07 Jan 2003)
    | 3 lines
    ...

If you run svn log on a specific path and provide a specific revision and get no output at all:

    $ svn log -r 20 http://svn.red-bean.com/untouched.txt
    ------------------------------------------------------------------------

That just means that the path was not modified in that revision. If you log from the top of the repository, or know the file that changed in that revision, you can specify it explicitly:

    $ svn log -r 20 touched.txt
    ------------------------------------------------------------------------
    r20 | sally | 2003-01-17 22:56:19 -0600 (Fri, 17 Jan 2003)
    | 1 line

    Made a change.
    ------------------------------------------------------------------------

merge
    svn merge sourceURL1[@N] sourceURL2[@M] [wcpath]
    svn merge -r N:M source [path]

In the first form, the source URLs are specified at revisions N and M. These are the two sources to be compared. The revisions default to HEAD if omitted.

In the second form, source can be a URL or working-copy item, in which case the corresponding URL is used. This URL, at revisions N and M, defines the two sources to be compared.

wcpath is the working-copy path that will receive the changes. If wcpath is omitted, a default value of "." is assumed, unless the sources have identical basenames that match a file within ".", in which case, the differences are applied to that file.

Unlike svn diff, this command takes the ancestry of a file into consideration when performing a merge operation. This is very important when you're merging changes from one branch into another and you've renamed a file on one branch but not the other.

Alternate names: none

Changes: working copy

Accesses repository: only if working with URLs

Options

--config-dir dir
--diff3-cmd cmd
--dry-run
--force
--ignore-ancestry
--no-auth-cache
--non-interactive
--non-recursive (-N)
--password pass
--quiet (-q)
--revision rev, -r rev
--username user

Examples

Merge a branch back into the trunk (assuming that you have a working copy of the trunk and that the branch was created in revision 250):

    $ svn merge -r 250:HEAD \
    > http://svn.red-bean.com/repos/branches/my-branch
    U  myproj/tiny.txt
    U  myproj/thhgttg.txt
    U  myproj/win.txt
    U  myproj/flo.txt

If you branched at revision 23, and you want to merge changes from the trunk into your branch, you could do this from inside the working copy of your branch:

    $ svn merge -r 23:30 file:///tmp/repos/trunk/vendors
    U  myproj/thhgttg.txt
    ...

To merge changes to a single file:

    $ cd myproj
    $ svn merge -r 30:31 thhgttg.txt
    U  thhgttg.txt

mkdir
    svn mkdir path ...
    svn mkdir URL ...

Create a directory with a name given by the final component of the path or URL. A directory specified by a working copy path is scheduled for addition in the working copy. A directory specified by a URL is created in the repository via an immediate commit. Multiple directory URLs are committed atomically. In both cases, all the intermediate directories must already exist.

Alternate names: none

Changes: working copy; repository if operating on a URL

Accesses repository: only if operating on a URL

Options

--config-dir dir
--editor-cmd editor
--encoding enc
--file file, -F file
--force-log
--message text, -m text
--no-auth-cache
--non-interactive
--password pass
--quiet (-q)
--username user
move
    svn move src dst

This command moves (renames) a file or directory in your working copy or in the repository.

NOTE

This command is equivalent to an svn copy followed by svn delete.

WC [image] WC

Move and schedule a file or directory for addition (with history).

URL [image] URL

Complete server-side rename.

NOTE

Subversion does not support moving between working copies and URLs. In addition, you can move files only within a single repository; Subversion does not support cross-repository moving.

Alternate names: mv, rename, ren

Changes: working copy; repository if operating on a URL

Accesses repository: only if operating on a URL

Options

--config-dir dir
--editor-cmd editor
--encoding enc
--file file, -F file
--force-log
--force
--message text, -m text
--no-auth-cache
--non-interactive
--password pass
--quiet (-q)
--revision rev, -r rev
--username user
propdel
    svn propdel propname [path ...]
    svn propdel propname --revprop -r rev [URL]

This removes properties from files, directories, or revisions. The first form removes versioned properties in your working copy, while the second removes unversioned remote properties on a repository revision.

Alternate names: pdel, pd

Changes: working copy; repository only if operating on a URL

Accesses repository: only if operating on a URL

Options

--config-dir dir
--no-auth-cache
--non-interactive
--password pass
--quiet (-q)
--recursive (-R)
--revision rev, -r rev
--revprop
--username user

Examples

Delete a property from a file in your working copy:

    $ svn propdel svn:mime-type some-script
    property 'svn:mime-type' deleted from 'some-script'.

Delete a revision property:

    $ svn propdel --revprop -r 26 release-date
    property 'release-date' deleted from repository revision
    '26'

propedit
    svn propedit propname path ...
    svn propedit propname --revprop -r rev [URL]

Edit one or more properties using your favorite editor. The first form edits versioned properties in your working copy, while the second edits unversioned remote properties on a repository revision.

Alternate names: pedit, pe

Changes: working copy; repository only if operating on a URL

Accesses repository: only if operating on a URL

Options

--config-dir dir
--editor-cmd editor
--encoding enc
--no-auth-cache
--non-interactive
--password pass
--revision rev, -r rev
--revprop
--username user
propget
    svn propget propname [path ...]
    svn propget propname --revprop -r rev [URL]

Print the value of a property on files, directories, or revisions. The first form prints the versioned property of an item or items in your working copy, while the second prints the unversioned remote property on a repository revision.

Alternate names: pget, pg

Changes: working copy; repository only if operating on a URL

Accesses repository: only if operating on a URL

Options

--config-dir dir
--no-auth-cache
--non-interactive
--password pass
--recursive (-R)
--revision rev, -r rev
--revprop
--strict
--username user
proplist
    svn proplist propname [path ...]
    svn proplist propname --revprop -r rev [URL]

List all properties on files, directories, or revisions. The first form lists versioned properties in your working copy, while the second lists unversioned remote properties on a repository revision.

Alternate names: plist, pl

Changes: working copy; repository only if operating on a URL

Accesses repository: only if operating on a URL

Options

--config-dir dir
--no-auth-cache
--non-interactive
--password pass
--quiet (-q)
--recursive (-R)
--revision rev, -r rev
--revprop
--username user
--verbose (-v)

Examples

You can use svn proplist to see the properties on an item in your working copy:

    $ svn proplist foo.c
    Properties on 'foo.c':
      svn:mime-type
      svn:keywords
      owner

But with the --verbose flag, svn proplist is extremely handy, as it also shows you the values for the properties:

    $ svn proplist --verbose foo.c
    Properties on 'foo.c':
      svn:mime-type : text/plain
      svn:keywords : Author Date Rev
      owner : sally

propset
    svn propset propname [propval] path ...
    svn propset propname --revprop -r rev [propval] [URL]

Set propname to propval on files, directories, or revisions. The first example creates a versioned, local property change in the working copy, and the second creates an unversioned, remote property change on a repository revision. The new property value, propval, may be provided literally, or using the -F valfile option.

Alternate names: pset, ps

Changes: working copy; repository only if operating on a URL

Accesses repository: only if operating on a URL

Options

--config-dir dir
--encoding enc
--file file, -F file
--force
--no-auth-cache
--non-interactive
--password pass
--quiet (-q)
--recursive (-R)
--revision rev, -r rev
--revprop
--targets filename
--username user

Examples

Set the mimetype on a file:

    $ svn propset svn:mime-type image/jpeg foo.jpg
    property 'svn:mime-type' set on 'foo.jpg'

On a Unix system, if you want a file to have the executable permission set:

    $ svn propset svn:executable ON somescript
    property 'svn:executable' set on 'somescript'

By default, you cannot modify revision properties in a Subversion repository. Your repository administrator must explicitly enable revision property modifications by creating a hook named pre-revprop-change.

resolved
    svn resolved path ...

Remove the conflicted state on working-copy files or directories. This command does not semantically resolve conflict markers; it merely removes conflict-related artifact files and allows path to be committed again; that is, it tells Subversion that the conflicts have been resolved. Use it after you have resolved the conflict in the file.

Alternate names: none

Changes: working copy

Accesses repository: no

Options

--config-dir dir
--quiet (-q)
--recursive (-R)
--targets filename

Example

If you get a conflict on an update, your working copy will contain three additional files:

    $ svn update
    C  foo.c
    Updated to revision 31.
    $ ls
    foo.c                   Merged version with conflict markers
    foo.c.mine              Original working copy version
    foo.c.r30               Unmodified BASE version
    foo.c.r31               Unmodified HEAD version

Once you've resolved the conflict and foo.c is ready to be committed, run svn resolved to let your working copy know you've taken care of everything.

NOTE

You can just remove the conflict files and commit, but svn resolved fixes up some bookkeeping data in the working-copy administrative area in addition to removing the conflict files, so you should use this command.

revert
    svn revert path ...

Revert any local changes to a file or directory, and resolve any conflicted states. svn revert reverts not only the contents of an item in your working copy, but also any property changes. Finally, you can use it to undo any scheduling operations that you may have done (e.g., files scheduled for addition or deletion can be unscheduled).

Alternate names: none

Changes: working copy

Accesses repository: no

Options

--config-dir dir
--quiet (-q)
--recursive (-R)
--targets filename

Examples

Discard changes to a file:

    $ svn revert foo.c
    Reverted foo.c

If you want to revert a whole directory of files, use the --recursive flag:

    $ svn revert --recursive .
    Reverted newdir/afile
    Reverted foo.c
    Reverted bar.txt

If you provide no targets to svn revert, it does nothing; to protect you from accidentally losing changes in your working copy, svn revert requires you to provide at least one target.

status
    svn status [path ...]

Print the status of working-copy files and directories. With no arguments, it prints only locally modified items (no repository access). With --show-updates, add working revision and server out-of-date information. With --verbose, print full revision information on every item.

The first five columns in the output are each one character wide, and each column gives you information about different aspects of each working-copy item.

The first column indicates that an item was added, deleted, or otherwise changed:

space

No modifications.

A

Item is scheduled for addition.

D

Item is scheduled for deletion.

M

Item has been modified.

C

Item is in conflict with updates received from the repository.

X

Item is related to an externals definition.

I

Item is being ignored (e.g., with the svn:ignore property).

?

Item is not under version control.

!

Item is missing (e.g., you moved or deleted it without using svn). This also indicates that a directory is incomplete (a checkout or update was interrupted).

~

Item is versioned as a directory but has been replaced by a file, or vice versa.

The second column tells the status of a file's or directory's properties:

space

No modifications.

M

Properties for this item have been modified.

C

Properties for this item are in conflict with property updates received from the repository.

The third column is populated only if the working copy directory is locked:

space

Item is not locked.

L

Item is locked.

The fourth column is populated only if the item is scheduled for addition-with-history:

space

No history scheduled with commit.

+

History scheduled with commit.

The fifth column is populated only if the item is switched relative to its parent:

space

Item is a child of its parent directory.

S

Item is switched.

If you pass the --show-updates option, the out-of-date information appears in the eighth column:

space

The item in your working copy is up to date.

*

A newer revision of the item exists on the server.

The remaining fields are variable width and delimited by spaces. The working revision is the next field if the --show-updates or --verbose options are passed.

If the --verbose option is passed, the last committed revision and last committed author are displayed next.

The working-copy path is always the final field, so it can include spaces.

Alternate names: stat, st

Changes: nothing

Accesses repository: only if using --show-updates

Options

--config-dir
--no-auth-cache
--no-ignore
--non-interactive
--non-recursive (-N)
--password pass
--quiet (-q)
--show-updates (-u)
--username user
--verbose (-v)

Examples

To find out what changes you have made to your working copy:

    $ svn status wc
     M     wc/bar.c
    A  +   wc/qax.c

To find out what files in your working copy are out of date, pass the --show-updates option (this does not make any changes to your working copy). Here you can see that wc/foo.c has changed in the repository since we last updated our working copy:

    $ svn status --show-updates wc
     M           965    wc/bar.c
           *     965    wc/foo.c
    A  +         965    wc/qax.c
    Status against revision:    981

NOTE

--show-updates places an asterisk only next to items that are out of date (that is, items that will be updated from the repository if you run svn update). --show-updates does not cause the status listing to reflect the repository's version of the item.

And finally, the most information you can get out of the status subcommand:

    $ svn status --show-updates --verbose wc
     M           965       938 sally        wc/bar.c
           *     965       922 harry        wc/foo.c
    A  +         965       687 harry        wc/qax.c
                 965       687 harry        wc/zig.c
    Head revision:   981

switch
    svn switch URL [path]

This subcommand updates your working copy to mirror a new URLusually a URL that shares a common ancestor with your working copy, although not necessarily. This is the Subversion way to move a working copy to a new branch.

Alternate names: sw

Changes: working copy

Accesses repository: yes

Options

--config-dir dir
--diff3-cmd cmd
--no-auth-cache
--non-interactive
--non-recursive (-N)
--password pass
--quiet (-q)
--relocate
--revision rev, -r rev
--username user

Examples

If you're currently inside the directory vendors, which was branched to vendors-with-fix, and you'd like to switch your working copy to that branch:

    $ svn switch http://svn.red-bean.com/repos/branches/ \
    > vendors-with-fix .
    U  myproj/foo.txt
    U  myproj/bar.txt
    U  myproj/baz.c
    U  myproj/qux.c
    Updated to revision 31.

And to switch back, just provide the URL to the location in the repository from which you originally checked out your working copy:

    $ svn switch http://svn.red-bean.com/repos/trunk/vendors .
    U  myproj/foo.txt
    U  myproj/bar.txt
    U  myproj/baz.c
    U  myproj/qux.c
    Updated to revision 31.

NOTE

You can just switch part of your working copy to a branch if you don't want to switch your entire working copy.

Sometimes an administrator might change the "base location" of your repository; in other words, the contents of the repository doesn't change, but the main URL used to reach the root of the repository does. For example, the hostname may change, or the URL schema, or perhaps just the path that leads to the repository. Rather than checking out a new working copy, you can have the svn switch command "rewrite" the beginnings of all the URLs in your working copy. Use the --relocate command to do the substitution. No file contents are changed, nor is the repository contacted. It's similar to running a sed script over your working copy .svn/ directories, which runs s/OldRoot/NewRoot/:

    $ cd /tmp
    $ svn checkout file:///tmp/repos test
    A  test/a
    A  test/b
    ...

    $ mv repos newlocation
    $ cd test/

    $ svn update
    svn: Unable to open an ra_local session to URL
    svn: Unable to open repository 'file:///tmp/repos'

    $ svn switch --relocate file:///tmp/repos file:///tmp/newlocation .
    $ svn update
    At revision 3.

update
    svn update [PATH ...]

svn update brings changes from the repository into your working copy. If no revision is given, it brings your working copy up to date with the HEAD revision. Otherwise, it synchronizes the working copy to the revision given by the --revision option.

For each updated item Subversion prints a line starting with a specific character reporting the action taken. These characters have the following meaning:

A

Added

D

Deleted

U

Updated

C

Conflict

G

Merged

A character in the first column signifies an update to the actual file, while updates to the file's properties are shown in the second column.

NOTE

If you want to examine an older revision of a single file, you may want to use svn cat.

Alternate names: up

Changes: working copy

Accesses repository: yes

Options

--config-dir dir
--diff3-cmd cmd
--no-auth-cache
--non-interactive
--non-recursive (-N)
--password pass
--quiet (-q)
--revision rev, -r rev
--username user


Section 14.5. Repository Administration: svnadmin

14.5. Repository Administration: svnadmin

svnadmin is the administrative tool for monitoring and repairing your Subversion repository.

14.5.1. svnadmin Options

--bdb-log-keep

(Berkeley DB specific) Disable automatic log removal of database logfiles.

--bdb-txn-nosync

(Berkeley DB specific) Disable use of fsync( ) when committing database transactions.

--bypass-hooks

Bypass the repository hook system.

--clean-logs

Remove unused Berkeley DB logs.

--force-uuid

By default, when loading data into a repository that already contains revisions, svnadmin ignores the UUID from the dump stream. This option causes the repository's UUID to be set to the UUID from the stream.

--ignore-uuid

By default, when loading an empty repository, svnadmin uses the UUID from the dump stream. This option causes that UUID to be ignored.

--incremental

Dump a revision only as a diff against the previous revision, instead of the usual full text.

--parent-dir dir

When loading a dumpfile, root paths at dir instead of /.

--quiet

Do not show normal progress; show only errors.

--revision rev, -r rev

Specify a particular revision to operate on.

14.5.2. svnadmin Subcommands

The svnadmin command creates and administers the repository. As such, it always operates on local paths, not on URLs.

create
    svnadmin create repos_path

Create a new, empty repository at the path provided. If the provided directory does not exist, it is created for you.

Options

--bdb-log-keep
--bdb-txn-nosync

Example

Creating a new repository is just this easy:

    $ svnadmin create /usr/local/svn/repos

deltify
    svnadmin deltify [-r lower[:upper]] repos_path

svnadmin deltify only exists in 1.0.x due to historical reasons. This command is deprecated and no longer needed.

It dates from a time when Subversion offered administrators greater control over compression strategies in the repository. This turned out to be a lot of complexity for very little gain, and the feature was deprecated.

Options

--quiet
--revision rev, -r rev
dump
    svnadmin dump repos_path [-r lower[:upper]] [--incremental]

Dump the contents of filesystem to standard output in a dumpfile portable format, sending feedback to standard error. Dump revisions lower rev through upper rev. If no revisions are given, dump all revision trees. If only lower is given, dump that one revision tree.

Options

--incremental
--quiet
--revision rev, -r rev

Examples

Dump your whole repository:

    $ svnadmin dump /usr/local/svn/repos
    SVN-fs-dump-format-version: 1
    Revision-number: 0
    * Dumped revision 0.
    Prop-content-length: 56
    Content-length: 56
    ...

Incrementally dump a single transaction from your repository:

    $ svnadmin dump /usr/local/svn/repos -r 21 --incremental
    * Dumped revision 21.
    SVN-fs-dump-format-version: 1
    Revision-number: 21
    Prop-content-length: 101
    Content-length: 101
    ...

help
    svnadmin help [subcommand ...]

Provide a quick usage summary. With subcommand, provide information about the given subcommand.

Alternate names: ?, h

hotcopy
    svnadmin hotcopy old_repos_path new_repos_path

This subcommand makes a full hot backup of your repository, including all hooks, configuration files, and, of course, database files. If you pass the --clean-logs option, svnadmin performs a hotcopy of your repository, and then removes unused Berkeley DB logs from the original repository. You can run this command at any time and make a safe copy of the repository, regardless of whether other processes are using the repository.

Option

--clean-logs
list-dblogs
    svnadmin list-dblogs repos_path

List Berkeley DB logfiles. Berkeley DB creates logs of all changes to the repository, which allow it to recover in the face of catastrophe. Unless you enable DB_LOGS_AUTOREMOVE, the logfiles accumulate, although most are no longer used and can be deleted to reclaim disk space.

list-unused-dblogs
    svnadmin list-unused-dblogs repos_path

Remove unused Berkeley DB logfiles (see svnlook list-dblogs).

Example

Remove all unused logfiles from a repository:

    $ svnadmin list-unused-dblogs /path/to/repos | xargs rm
    ## disk space reclaimed!

load
    svnadmin load repos_path

Read a dumpfile-formatted stream from standard input, committing new revisions into the repository's filesystem. Send progress feedback to standard output.

Options

--force-uuid
--ignore-uuid
--parent-dir
--quiet (-q)

Examples

This shows the beginning of loading a repository from a backup file (made, of course, with svn dump):

    $ svnadmin load /usr/local/svn/restored < repos-backup
    <<< Started new txn, based on original revision 1
         * adding path : test ... done.
         * adding path : test/a ... done.
    ...

Or, to load into a subdirectory:

    $ svnadmin load --parent-dir new/subdir/for/project \
    >   /usr/local/svn/restored < repos-backup
    <<< Started new txn, based on original revision 1
         * adding path : test ... done.
         * adding path : test/a ... done.
    ...

lstxns
    svnadmin lstxns repos_path

Print the names of all uncommitted transactions.

recover
    svnadmin recover repos_path

Run this command if you get an error indicating that your repository needs to be recovered.

rmtxns
    svnadmin rmtxns repos_path txn_name ...

Delete outstanding transactions from a repository.

Options

--quiet (-q)

Examples

Remove all uncommitted transactions from your repository, using svn lstxns to provide the list of transactions to remove:

    $ svnadmin rmtxns /usr/local/svn/repos/ \
    >          `svnadmin lstxns /usr/local/svn/repos/`

setlog
    svnadmin setlog repos_path -r revision file

Set the log message on revision revision to the contents of file.

This is similar to using svn propset --revprop to set the svn:log property on a revision, except that you can also use the option --bypass-hooks to avoid running any pre- or post-commit hooks, which is useful if the modification of revision properties has not been enabled in the pre-revprop-change hook.

Revision properties are not under version control, so this command permanently overwrites the previous log message.

Options

--bypass-hooks
--revision rev, -r rev

Example

Set the log message for revision 19 to the contents of the file msg:

    $ svnadmin setlog /usr/local/svn/repos/ -r 19 msg

verify
    svnadmin verify repos_path

Run this command to verify the integrity of your repository. This iterates through all revisions in the repository by internally dumping all revisions and discarding the output.


Section 14.6. Examining the Repository: svnlook

14.6. Examining the Repository: svnlook

svnlook is a command-line utility for examining different aspects of a Subversion repository. It does not make any changes to the repository. svnlook is typically used by the repository hooks, but a repository administrator might find it useful for diagnostic purposes.

Since svnlook works via direct repository access (and thus can only be used on the machine that holds the repository), it refers to the repository with a path, not a URL.

If no revision or transaction is specified, svnlook defaults to the youngest (most recent) revision of the repository.

14.6.1. svnlook Options

Options in svnlook are global, just as in svn and svnadmin; however, most options apply to only one subcommand because the functionality of svnlook is (intentionally) limited in scope.

--no-diff-deleted

Do not print differences for deleted files. The default behavior when a file is deleted in a transaction/revision is to print the same differences that you would see if you had left the file but removed all the content.

--revision rev, -r rev

Examine revision number rev.

--show-ids

Show the filesystem node revision IDs for each path in the filesystem tree.

--transaction tid, -t tid

Examine transaction ID tid.

--verbose

Show property values for the property-related commands, too.

--version

Display version and copyright information.

14.6.2. svnlook Subcommands

author
    svnlook author repos_path

Print the author of a revision or transaction in the repository.

Options

--revision rev, -r rev
--transaction tid, -t tid
cat
    svnlook cat repos_path path_in_repos

Print the contents of a file.

Options

--revision rev, -r rev
--transaction tid, -t tid
changed
    svnlook changed repos_path

Print the paths that were changed in a particular revision or transaction, as well as an svn update-style status letter in the first column: A for added, D for deleted, and U for updated (modified).

Options

--revision rev, -r rev
--transaction tid, -t tid

Example

Show a list of all the changed files in revision 39 of a test repository:

    $ svnlook changed -r 39 /usr/local/svn/repos
    A   trunk/vendors/deli/
    A   trunk/vendors/deli/chips.txt
    A   trunk/vendors/deli/sandwich.txt
    A   trunk/vendors/deli/pickle.txt

date
    svnlook date repos_path

Print the datestamp of a revision or transaction in a repository.

Options

--revision rev, -r rev
--transaction tid, -t tid
diff
    svnlook diff repos_path

Print GNU-style differences of changed files and properties in a repository. If a file has a nontextual svn:mime-type property, the differences are explicitly not shown.

Options

--no-diff-deleted
--revision rev, -r rev
--transaction tid, -t tid
dirs-changed
    svnlook dirs-changed repos_path

Print the directories that were themselves changed (property edits) or whose file children were changed.

Options

--revision rev, -r rev
--transaction tid, -t tid
help
    svnlook help
    svnlook -h
    svnlook -?

Provide a quick usage summary. With subcommand, provide information about the given subcommand.

Alternate names: ?, h

history
    svnlook history repos_path [path_in_repos]

Print information about the history of a path in the repository (or the root directory if no path is supplied).

Options

--revision rev, -r rev
--show-ids

Example

This shows the history output for the path /tags/1.0, as of revision 20 in our sample repository.

    $ svnlook history -r 20 /usr/local/svn/repos /tags/1.0 \
    > --show-ids
    REVISION   PATH <ID>
    --------   ---------
          19   /tags/1.0 <1.2.12>
          17   /branches/1.0-rc2 <1.1.10>
          16   /branches/1.0-rc2 <1.1.x>
          14   /trunk <1.0.q>
    ...

info
    svnlook info repos_path

Print the author, datestamp, log message size, and log message.

Options

--revision rev, -r rev
--transaction tid, -t tid
log
    svnlook log repos_path

Print the log message.

Options

--revision rev, -r rev
--transaction tid, -t tid
propget
    svnlook propget repos_path propname path_in_repos

List the value of a property on a path in the repository.

Alternate names: pg, pget

Options

--revision rev, -r rev
--transaction tid, -t tid

Example

Show the value of the seasonings property on the file /trunk/sandwich in the HEAD revision:

    $ svnlook pg /usr/local/svn/repos seasonings /trunk/sandwich
    mustard

proplist
    svnlook proplist repos_path path_in_repos

List the properties of a path in the repository. With --verbose, show the property values too.

Alternate names: pl, plist

Options

--revision rev, -r rev
--transaction tid, -t tid
--verbose (-v)

Examples

Show the names of properties set on the file /trunk/README in the HEAD revision:

    $ svnlook proplist /usr/local/svn/repos /trunk/README
    original-author
    svn:mime-type

This is the same command as in the previous example, but this time it shows the property values as well:

    $ svnlook proplist --verbose /usr/local/svn/repos \
    > /trunk/README
    original-author : fitz
    svn:mime-type : text/plain

tree
    svnlook tree repos_path[path_in_repos]

Print the tree, starting at path_in_repos (if supplied; at the root of the tree otherwise), optionally showing node revision IDs.

Options

--revision rev, -r rev
--show-ids
--transaction tid, -t tid

Example

This shows the tree output (with node IDs) for revision 40 in our sample repository:

    $ svnlook tree -r 40 /usr/local/svn/repos --show-ids
    / <0.0.2j>
     trunk/ <p.0.2j>
      vendors/ <q.0.2j>
       deli/ <1g.0.2j>
        egg.txt <1i.e.2j>
        soda.txt <1k.0.2j>
        sandwich.txt <1j.0.2j>

uuid
    svnlook uuid repos_path

Print the UUID for the repository. The UUID is the repository's Universal Unique IDentifier. The Subversion client uses this identifier to differentiate between one repository and another.

youngest
    svnlook youngest repos_path

Print the youngest revision number of a repository.


Section 14.7. Providing Remote Access: svnserve

14.7. Providing Remote Access: svnserve

svnserve allows access to Subversion repositories using the svn network protocol. You can run svnserve either as a standalone server process, or by having another processsuch as inetd, xinetd, or sshd--start it for you.

Once the client has selected a repository by transmitting its URL, svnserve reads a file named conf/svnserve.conf in the repository directory to determine repository-specific settings, such as what authentication database to use and what authorization policies to apply. The details are provided in Version Control with Subversion (O'Reilly).

14.7.1. svnserve Options

Unlike the previous commands we've described, svnserve has no subcommands; svnserve is controlled exclusively by options.

--daemon, -d

Run in daemon mode. svnserve backgrounds itself, and accepts and serves TCP/IP connections on the svn port (3690, by default).

--foreground

When used together with -d, this option causes svnserve to stay in the foreground. This option is mainly useful for debugging.

--help, -h

Display a usage summary and exit.

--inetd, -i

Use the standard input/standard output file descriptors, as appropriate for a server running out of inetd.

--listen-host=host

Listen on the interface specified by host, which may be either a hostname or an IP address.

--listen-once, -X

Accept one connection on the svn port, serve it, and exit. This option is mainly useful for debugging.

--listen-port=port

Listen on port when run in daemon mode.

--root=root, -r=root

Set the virtual root for repositories served by svnserve to root. The pathname in URLs provided by the client are interpreted relative to this root and are not allowed to escape this root.

--threads, -T

When running in daemon mode, spawn a thread instead of a process for each connection. The svnserve process still backgrounds itself at startup time.

--tunnel, -t

Run in tunnel mode, which is just like the inetd mode of operation (serve one connection over standard input/standard output), except that the connection is considered to be pre-authenticated with the username of the current UID. This flag is selected by the client when running over a tunnelling agent such as ssh.


Section 14.8. Other Subversion Components

14.8. Other Subversion Components

Subversion creates the mod_dav_svn plug-in for use with the Apache 2.0 httpd web server. By running Apache 2.0 with mod_dav_svn, you can make your repository available via the HTTP protocol. Full details are provided in Version Control with Subversion (O'Reilly). Two other commands are supplied with Subversion.

svndumpfilter
    svndumpfilter subcommand [options] paths ...

Filter out files from a repository dump for use in later repository restoration (see svnadmin dump and svnadmin load).

Subcommands

exclude

Exclude from the dump the files and directories named by paths. Everything else is left in the dump.

help, h, ?

Print a help message and exit.

include

Include in the dump only the files and directories named by paths. Everything else is excluded.

Options

--drop-empty-revs

Remove empty revisions. Such revisions can be created when the original revision contained paths that were filtered out. This option removes empty revisions from the dump.

--preserve-revprops

If empty revisions are being kept, preserve their revision properties (such as log message, author, date, etc.). Otherwise, empty revisions contain only the original datestamp and a generated log message that the revision was dropped.

--renumber-revs

If empty revisions are being dropped, renumber subsequent revisions, so that all revision numbers are contiguous.

Example

Dump the repository, and then separate out its two components:

    $ svnadmin dump /path/to/repos > dumpfile
    * Dumped revision 0.
    * Dumped revision 1.
    * Dumped revision 2.
    ...

    $ svndumpfilter include client < dumpfile > client-dumpfile
    $ svndumpfilter include server < dumpfile > server-dumpfile

svnversion
    svnversion [options] path [URL]

Produce a version number for the working copy in path. The URL is the pathname part of a Subversion URL used to tell if the path was switched (see svn switch).

The output is a single number if the working copy represents an unmodified, nonswitched revision whose URL matches the supplied URL.

Options

-c

Report "last changed" revision instead of the current revision.

-n

Do not print the final newline.


Colophon

Colophon

    About the Authors

    Colophon


About the Authors

Ellen Siever is a writer and editor specializing in Linux and other open source topics. In addition to Linux in a Nutshell, she coauthored O'Reilly's Perl in a Nutshell. She is a longtime Linux and Unix user and was a programmer for many years until she decided that writing about computers was more fun.

Aaron Weber is a technical and marketing writer for Novell, Inc. and also contributed sections on GNOME and software management to O'Reilly's Running Linux. You can find him at secretlyironic.com.

Stephen Figgins administrates Linux servers for Sunflower Broadband in Lawrence, Kansas. He also writes, edits, and consults on computing topics. He balances this with his study of nature.Through the Plainscraft school of living (http://www.plainscraft.com), he teaches wilderness awareness and survival skills, including animal tracking, edible and medicinal plants, and matchless fire making.

Robert Love is a contributing editor at Linux Journal and authored Linux Kernel Development (Sams).He works in Novell's Ximian Desktop Group as a kernel hacker and graduated from the University of Florida with degrees in mathematics and computer science.

Arnold Robbins, an Atlanta native, is a professional programmer and technical author.He is also a happy husband, the father of four very cute children, and an amateur Talmudist (Babylonian and Jerusalem).Since late 1997, he and his family have been living in Israel.Arnold has been working with Unix systems since 1980, when he was introduced to a PDP-11 running a version of Sixth Edition Unix. Arnold has also been a heavy awk user since 1987, when he became involved with gawk, the GNU project's version of awk. As a member of the POSIX 1003.2 balloting group, he helped shape the POSIX standard for awk. He is currently the maintainer of gawk and its documentation.


Colophon

Our look is the result of reader comments, our own experimentation, and feedback from distribution channels.Distinctive covers complement our distinctive approach to technical topics, breathing personality and life into potentially dry subjects.

The animal featured on the cover of Linux in a Nutshell, Fifth Edition is an Arabian horse. Known for its grace and intelligence, the Arabian is one of the oldest breeds of horse, with evidence of its existence dating back 5000 years. The Arabian was instrumental as an ancestor to other popular breeds, most notably the Thoroughbred in the 17th and 18th centuries. Possibly one of the more distinctive horse breeds, the typical Arabian has large, expressive eyes and nostrils, small ears, and a short, sturdy back. Its stamina suits it particularly well for endurance riding, a sport dominated by the Arabian breed. Its wonderful temperament makes the Arabian an all-around favorite riding horse in North America, although it also can be found in more specialized competitions such as dressage, jumping, and reining.

Sanders Kleinfeld was the production editor and proofreader for Linux in a Nutshell, Fifth Edition. Adam Witwer and Claire Cloutier provided quality control. Ellen Troutman-Zaig wrote the index.

Edie Freedman designed the cover of this book, using a 19th-century engraving from the Dover Pictorial Archive. Karen Montgomery produced the cover layout with Adobe InDesign CS using Adobe's ITC Garamond font.

David Futato designed the interior layout.This book was converted by Keith Fahlgren to FrameMaker 5.5.6 with a format conversion tool created by Erik Ray, Jason McIntosh, Neil Walls, and Mike Sierra that uses Perl and XML technologies. The text font is Linotype Birka; the heading font is Adobe Myriad Condensed; and the code font is LucasFont's TheSans Mono Condensed. The illustrations that appear in the book were produced by Robert Romano, Jessamyn Read, and Lesley Borash using Macromedia FreeHand MX and Adobe Photoshop CS. The tip and warning icons were drawn by Christopher Bing.


Index

[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]


SYMBOL

Index

[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]

! (exclamation mark)
!= inequality operator 2nd
!~ regular expression nonmatch
ex command
ftp command
negating a pipeline, ksh
negation in sed
negation operator
" " (quotation marks, double)
metacharacters for pattern matching and filename expansion
quoting in bash and ksh
# (hash mark)
#! command, in shell scripts
.#file.revision
comments in awk
comments in sed
comments in shell scripts
#define statements (C), generating template file from
$ (dollar sign)
execute macro command, ftp
field reference operator
metacharacter
prompt, bash and ksh commands
$HOME/.profile file 2nd
${ ... } syntax, referencing arrays
% (percent)
%= assignment operator 2nd
diff, format strings for
metacharacter in replacement patterns
modulus operator 2nd
prompt
& (ampersand)
&& AND operator 2nd
&= assignment operator
AND operator
ex command
metacharacter in replacement patterns
' ' (quotation marks, single)
metacharacters for pattern matching and filename expansion
quoting in bash and ksh
( ) (parentheses)
escaped
grouping in regular expression pattern matching
in bc expressions
shell patterns
* (asterisk)
** exponentiation operator 2nd
*= assignment operator 2nd
metacharacter
multiplication operator 2nd
+ (plus sign)
++ auto-increment operator 2nd
+= assignment operator 2nd
addition operator 2nd
metacharacter in pattern matching
unary operator
, (comma) operator
- (hyphen)
- - auto-decrement operator 2nd
-= assignment operator 2nd
in character ranges
metamail command arguments
negation operator
subtraction operator 2nd
tag names
. (dot) command, bash and ksh
. (dot) files
. (dot), metacharacter
.#file.revision
.cvsignore file
.cvspass file
.cvsrc file
.cvswrappers file
.exrc file (example)
.rhosts file
/ (slash)
/* */, enclosing bc comments
/= assignment operator 2nd
division operator 2nd
: (colon)
bash and ksh command
ex editor
sed command
:set command (vi)
; (semicolon), ;& instead of ;; ending ksh case
< (left angle bracket)
<< bitwise shift operator
<<= assignment operator
<= less than or equal operator 2nd
ex command
less than operator 2nd
= (equal sign)
= = equality operator 2nd
assignment operator 2nd
ex command
sed command
> (right angle bracket)
>= greater than or equal operator 2nd
>> bitwise shift operator
>>= assignment operator
ex command
greater than operator 2nd
? (question mark)
?: inline conditional evaluation 2nd
??, printed by addr2line
ftp help command
metacharacter in pattern matching
regular expression pattern matching and filename expansion
@ (at), ex command
[ ] (brackets)
[[ ]] command, bash and ksh
array index in bc
enclosing character classes
metacharacter in pattern matching
optional elements in syntax descriptions
\ (backslash)
escaping metacharacters
quoting in bash and ksh
\", beginning of an Emacs buffer
\', end of an Emacs buffer
\( \) metacharacters, enclosing subpatterns
\B (interword match)
\b (word boundary) escape sequence
\e in replacement patterns
\E in replacement patterns
\L (lowercase), all characters in replacement pattern
\l (lowercase), first character in replacement pattern
\U (uppercase), all characters in replacement pattern
\u (uppercase), first character in replacement pattern
\W, matching any non-word character
\w, matching any word character
^ (caret)
^= assignment operator 2nd
exclusive OR operator
exponentiation operator
metacharacter in pattern matching
beginning of line assertion
inverting character class
_ (underscores)
tag names
{ } (braces)
grouping statements in bc
metacharacter in pattern matching
sed editor, nesting command addresses
| (continued)
alternation in pattern matching
in syntax descriptions
multiple patterns separated by
OR operator
| (vertical bar)
|& operator, two-way pipe to another process
|= assignment operator
|| OR operator 2nd
~ (tilde)
mail formatting escape sequences
metacharacter in replacement patterns
negation operator
regular expression match operator
shell variables, CVS
ssh escape characters
~ !~ match regular expression and negation
~ (tilde), ex command


A

Index

[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)
abbreviate command (ex)
abbreviation of words, Emacs
accept command
access command
access mode, changing for files
account command (ftp)
acipd daemon
aclocal command
aconnect command
acpi command
acpi_available command
add command
cvs
svn
addresses command
addresses for ex commands
addresses for sed commands
ADF (automatic document feeder), controlling scanners
admin command (CVS)
administration
Advanced Configuration and Power Interface (ACPI)
Advanced Package Tool
agents, ssh
agetty command
alias command
lftp
aliases
bash and ksh commands
for commands
printing current sendmail aliases
rebuilding mail aliases database
alnum character class
alpha character class
ALSA (Advanced Linux Sound Architecture)
mixer
playing MIDI files
playing sound files with aplay
raw MIDI files, reading/writing
recording MIDI files
recording sound
alsactl command
alsamixer command
Alt key, used for Emacs Meta
Alt-F1 through F12
Alt-F7
amidi command
anacron command
and function (gawk)
annotate command (CVS)
anon command (lftp)
ANSI/VT100 emulation
Apache web server
user authentication files, updating
aplay command
aplaymidi command
APM (Advanced Power Management)
GRUB displayapm command
apm command
apmd command
append command (ex)
append command, ftp
apropos command
apt command
apt-cache command (Debian)
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)
aptitude command (Debian)
ar command
Arch (source code management system)
arch command
archives
copying with cpio
creating and restoring (tar)
generating indexes for
maintenance (ar)
arecord command
args command (ex)
arguments (command), reading from standard input
arithmetic (arbitrary-precision), with bc
arithmetic expressions, bash and ksh 2nd
arithmetic operators
bc program
expr command
ARP (Address Resolution Protocol)
arp command
ifconfig and
arrays
assigning in awk
in operator (awk)
Korn shell
RAID device
as command
ascii command (ftp)
asort function (gawk)
asorti function (gawk)
ASs (autonomous systems)
assembly language, generation of object files
assignment operators
awk
bash and ksh shells
bc program
associative arrays 2nd
at (@) command (ex)
at command
batch command
lftp
at.allow file
at.deny file
atan2 function (awk)
atd command
atomic commits (Subversion)
atrm command
attributes, terminal, setting
audio media commands
audiosend command
aumix command
authentication keys for ssh
author command (svnlook)
autoconf command
autoheader command
autoload command (ksh)
automake command
automatic document feeder (ADF), controlling scanners with
autoreconf command
autoscan command
autoupdate command
awk programming language
command-line syntax
gawk options
standard options
functions and commands
group listing
listed by name
implementation limits
operators
pattern-matching metacharacters
patterns and procedures
examples
searching with regular expressions
source code, URLs for
variable and array assignment
variables, built-in


B

Index

[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)
backups
magnetic tape drive
performing with dump command
bad blocks
checking MS-DOS filesystems for
bad login attempts, displaying
badblocks command
banner command
basename command
bash (Bourne-Again shell) 2nd 3rd
arithmetic expressions
built-in commands
command execution
command history
programmable completion
features
bash (continued)
functions
invoking
arguments
common options
job control
setting restrictions on
syntax
command forms
filename metacharacters
quoting
redirection
startup files
variables
arrays
built-in
other
special prompt strings
batch command
bc program
examples
function keywords
identifiers
input-output keywords
math library functions
operators and symbols
statement keywords
bdelete command (ex)
bell command (ftp)
Berkeley C shell (csh)
bg command 2nd
biff command
binary command (ftp)
binary files, encoding in ASCII (uuencode)
BIND (Berkeley Internet Name Domain)
bind command (bash)
BIND DNS server, sending commands to via TCP
binder process, NIS (ypbind)
bindtextdomain function (gawk)
biod daemon
bison command
blame command (svn)
blank character class
block files
blocklist command (GRUB)
blocks
bad, checking MS-DOS filesystems for
bad, searching device for
printing information about with dumpe2fs
Boleyn, Erich
bookmark command (lftp)
boot command (GRUB)
boot loaders 2nd
chainloaders
GRUB
init command, running
LILO
boot methods 2nd
boot process
boot sector
boot-time kernel options
booting, reboot command
bootp command (GRUB)
Bourne shell
branches, development 2nd
efficient branching with Subversion
branching commands (sed)
break command
awk
broadcast messaging (wall)
BSD (Berkeley Software Distribution), ix
license for Linux tools
system and network administration tools
buffer command (ex)
buffers
Emacs
commands for
Emacs, beginning and end of
buffers command (ex)
builtin command
bash
ksh
bye command (ftp)
bzcmp command
bzdiff command
bzgrep command
bzip2 command
bzless command
bzmore command


C

Index

[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 and C++
#define statements, generating template file of
C language preprocessor
debugging with gdb
gcc compiler
invoking gcc so it recognizes C++
m4 command (C)
macro processor for C
c command (sed)
C shell (csh) 2nd
c++ command
c++filt command
cache command (lftp)
caching font information, for fontconfig
cal command
caller command (bash)
canceling commands, Emacs
cardctl command
cardmgr command
carriage returns
cr command (ftp)
case command
ftp
case shell keyword
case, Emacs commands for
cat (concatenate) command
GRUB
svn
svnlook
cc command
CCVSROOT variables
cd command
ex
ftp
CD-ROM volume names, displaying (volname)
cdda2wav command
cdparanoia command
cdrdao command
cdrecord command
device argument
general options
CDs
bootable, difficulties of making
readcd command
cdup command (ftp)
center command (ex)
centering commands, Emacs
cfdisk command
chage command
chainloader command (GRUB) 2nd
chainloaders
chains
change command (ex)
changed command (svnlook)
channels
character classes 2nd
character encoding conversions (iconv)
character files
character order, reversing on lines of a file
characters, translating
chattr command
check in, check out 2nd
check out with locking model, source code management
check-update command (yum)
checkout command
cvs
svn
checksums
calculating for files with sum
MD5, computing or checking
SHA1, computing or checking
chfn command
chgrp command
chkconfig command
chmod command
ftp
chown command
chpasswd command
chroot command
chrt command
chsh command
chvt command
cksum command
classes, character 2nd
Classless Inter-Domain Routing (CIDR)
clean command (yum)
cleanup command (svn)
clear command
client/server model for source code storage
clients (NIS), setting up
clock commands
clock, setting (hwclock)
close command
ftp
lftp
close command (ex)
close function (awk)
cmp command
GRUB
cntrl character class
Codeville (source code management system)
col command
colcrt command
color command (GRUB)
color options for ls
colrm command
column command
columned version of text files
comm command
command command
lftp
command execution, bash and ksh
command history
bash and ksh shells
common editing keystrokes
fc and hist commands
line-edit mode
command mode (vi)
command-line tools
commands
aliases for 2nd
awk programming language
listed by group
listed by name
bash and ksh shells
execution
job control
syntax
CVS
Debian Package Manager
Emacs
buffer manipulation
capitalization
centering
Ctrl and Meta keys
Ctrl-key
cursor movement
deletion
essential
file handling
help
indentation
listed by name
macro
Meta-key
paragraphs and regions
search
special shell characters
stopping and undoing
transposition
window
word abbreviation
ex editor, listed alphabetically
executing as superuser (sudo)
executing at specified time
executing with arguments from standard input (xargs)
executing with doexec
GRUB
Linux 2nd
beginner's guide
listing pathnames of executed files (which)
running repeatedly (watch)
sed editor
alphabetical summary
basic editing
branching
I/O processing
line information
multiline input processing
syntax
yanking and putting
Subversion svn client
svnadmin
svnlook
svnserve
system administration
vi editor
accessing multiple files
edit
insert
interaction with system
macros
miscellaneous
movement
saving and exiting
status-line
syntax
window
yum
comments
awk language
bash and ksh shells
bc program
sed editor
commit command
svn
commitcommand
cvs
commits, atomic
Common UNIX Printing System (CUPS)
configuring printer queues
lpr command
communication commands
comp.os.linux newsgroups
comparison commands
bzcmp
bzdiff
cmp
comm
diff
diff3
compgen command (bash) 2nd
compilers
bc
gcc
preprocessor for C (cpp)
yacc
compl function (gawk)
complete command (bash) 2nd
completion facilities (bash)
compress command
concatenate commands
cat
mcat
configfile command (GRUB)
configuration files
chkconfig command
rpm command
scanning with autoscan
updating with autopupdate
vi
yum
configuration scripts
generating with autoconf
updating with autoreconf
conflicts, source code documents 2nd
continue command
awk
Convert Compact Disc Digital Audio (CDDA)
coprocesses
awk
Korn shell
copy command
ex
svn
copy, modify, merge development model
CVS and Subversion
Subversion
copyleft
cos function (awk)
country codes, top-level domains
country-specific settings, displaying
cp command
cpio command
cpp command 2nd
directives
special names
CPU usage for processes
cr command (ftp)
create command (svnadmin)
cron jobs
anacron command
removing old files in /tmp directory
crond command
crontab command
csh (Berkeley C shell)
csplit command
CSSC (free clone of SCCS)
ctags command
Ctrl-key commands (Emacs) 2nd
Ctrl-Z, suspending foreground jobs
cupsd command 2nd
current working directory, identifying with pwd
cursor, Emacs
cursor-movement commands, Emacs
cut and paste (Emacs)
cut command
CVS (Concurrent Versions System) 2nd 3rd 4th 5th
command-line syntax and options
commands, alphabetical summary
conceptual overview
CVS wrappers
stickiness
copy, modify, merge model
dates and times
legal date formats
legal date keywords
time zones
dot files
environment variables
client
server
keywords and keyword modes
cvs command
CVS_USER environment variable
CVSEDITOR internal variable
CVSROOT variables
internal
shell variables in CVSROOT files
cyclic redundancy checks (CRCs), performing


D

Index

[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)
daemons
commands
defined
NFS daemons
routing daemons
xinetd
DAO (disk-at-once) mode
database maps for use by sendmail
databases, searching for specified key
date keywords (CVS)
dates and times
cal command
CVS
legal date formats
legal date keywords
time zones
date command
formats
strings for setting the date
svnlook
displaying time zone information (zdump)
executing commands
rdate command
setting hardware clock
tcpslice command
time command 2nd
time conversion information files
times command
units of time for sleep command
dbm files
creating (makedbm)
dcgettext function (gawk)
dcngettext function (gawk)
dd command
deallocvt command
Debian package management system
apt command
Debian Package Manager
commands
files
package flags
package priorities
package/selection states
shell and Perl scripts
debug command
ftp
GRUB
debugfs command
debugging tools
addr2line
gdb program
gprof
patch command
declare command (bash)
decryption, GPG commands
delete command
awk
ex
ftp
svn
deletion commands (Emacs)
deltify command (svnadmin)
dependencies
depmod command
desktop environments
GNOME
Desktop Link Protocol (DLP) shell
devdump command
development versions (Subversion)
device command (GRUB)
devices
elevator algorithm for I/O activities
formatting as MS-DOS filesystem
hard disks as
df command
dhcp command (GRUB)
diff command
cvs
svn
svnlook
diff3 command
differences between files
consistent data handling in Subversion
rdiff command
sdiff command
zdiff command
dig command 2nd 3rd
query options
digit character class
dir command
ftp
dircolors command
directives
cpp
gcc pragma directives
logrotate
directories
changing (cd)
changing on MS-DOS
creating (mkdir)
creating on MS-DOS filesystem
deleting with rmdir
displaying verbosely (vdir)
identifying current working directory with pwd
listing contents on MS-DOS
listing contents with ls
lost+found
moving or renaming with mv
MS-DOS
deleting
moving or renaming
renaming
directory versioning (Subversion)
dirname command
dirs command (bash)
dirs-changed command (svnlook)
disable command
discipline functions (ksh93)
disconnect command (ftp)
disk space available
disk usage
auditing and correcting quota information
displaying space allowed for user or group
displaying with du
generating report on with repquota
quota enforcement, turning off
quota enforcement, turning on
RAM disk
disk usage, displaying on MS-DOS
disk-at-once (DAO) mode
disks
checking and repairing with e2fsck
fdisk command
disown command
bash
ksh93
displayapm command (GRUB)
displaymem command (GRUB)
distribution client for files
distribution server for files, starting
distributions
dlpsh command
dmesg command
DNS (Domain Name Service)
domain name server (named)
querying servers with dig
dnsdomainname command
dnssec-keygen command
dnssec-makekeyset command
dnssec-signkey command
dnssec-signzone command
do command (awk)
do shell keyword
document formatting commands
groff
gs
documentation, accessing
info command
manpath command
whatis command
doexec command
domain names
researching (whois)
domainname command 2nd 3rd
domains
NIS
done shell keyword
DOS 8.3 filenames
dosfsck command
dot files
dpkg command (Debian) 2nd
dpkg-deb command (Debian) 2nd
dpkg-query command (Debian)
dpkg-split command (Debian)
dselect command (Debian) 2nd
du (disk usage) command
dual booting
Linux and Windows NT/2000/XP
dual-boot system
dump command
GRUB
svnadmin
dumpe2fs command
dumpkeys command


E

Index

[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]

e command (sed)
e2fsck command
e2image command
e2label command
echo command
bash
ksh
ed editor
metacharacters in replacement patterns
pattern-matching metacharacters
searching with regular expressions
edit command
CVS
ex
edit commands, vi editor
copying and moving
editing keystrokes (common), bash and ksh
editing, sed commands for
EDITOR internal variable (cvs)
editors 2nd
Emacs
ex 2nd
sed 2nd
vi 2nd
vim
editors command (CVS)
edquota command
egrep command
pattern-matching metacharacters
regular expressions
eject command
ELF (Executable and Linking Format)
displaying information about object files
elvis text editor
elvtune command
Emacs editor 2nd
beginning of a buffer (\")
buffers
command-line syntax
commands
buffer manipulation
captialization
centering
Ctrl-key
cursor movement
deletion
essential
file handling
help
indentation
listed by name
macro commands
Meta-key
paragraphs and regions
search
special shell characters
stopping and undoing
transposition
window
word abbreviation
etags command
kill and yank
modes
Emacs editor (continued)
point and mark
windows
embed command (GRUB)
enable command
enable command (bash)
encrypted DNSSEC or TSIG keys for domain name
encryption
GPG (GNU Privacy Guard)
Enlightened Sound Daemon
env command
ENV environment variable
environment variables
CVS
client
server
CVSROOT directory
printing values of
envsubst command
EOF (end-of-file) character
esac shell keyword
Escape key, using for Meta in Emacs
escape sequences, awk
esd command
esd-config command
esdcat command
esdctl command
esddsp command
esdmon command
esdplay command
esdrec command
esdsample command
EsounD
etags command
eval command
ex command
ex editor 2nd 3rd
addresses for commands
command options
command syntax
commands, list of
metacharacters in replacement patterns
pattern-matching metacharacters
search-and-replace examples
searching with regular expressions
exec command
executing commands remotely
rexec command
rexecd command
rsh command
ssh command
exit command
awk
exp function (awk)
expand command
export command
cvs
svn
exports file
expr command
arithmetic operators
keywords
logical operators
relational operators
expressions, testing (test)
ext2 (Second Extended Filesystem)
creating with mkfs.ext2
disk formatting
resize2fs command
tuning (tune2fs)
ext3 (Third Extended Filesystem)
creating with mkfs.ext3
potential booting issues
extended Internet services daemon (xinetd)
extended regular expressions
GNU sed
recognizing with grep
Extensible Filesystem (XFS)
extension function (gawk)
eXternal Data Representation (XDR)
extglob option (bash and ksh)


F

Index

[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]

factor command
false command
bash and ksh
Fast Lexical Analyzer Generator (flex) command
FAT clusters, MS-DOS files
FAT filesystem
fc command 2nd 3rd
fc-cache command
fc-list command
fdformat command
fdisk command
fetchmail command
fflush function (gawk)
fg (foreground) command
fg command
fgconsole command
fgrep command
fi shell keyword
FIFOs (named pipes) 2nd
file attributes
changing for MS-DOS files (mattrib)
listing (lsattr)
modifying with chattr
file command (ex)
file compression
bzip2 format
compressed to uncompressed files (zcmp)
gunzip command
gzexe command
gzip command
reading compressed files to output (zcat)
renaming zipped files (zforce)
uncompress command
uncompressing .Z files and recompressing as .gz format
file descriptors
file distribution client program
file distribution server, starting
file inclusion facility for gawk
file management commands
chgrp
file properties (Subversion)
file storage commands
file transfer commands
ftp
lftp
lftpget
rsync
sftp
tftp
tftpd
filenames
metacharacters for filename expansion
metacharacters, bash and ksh
translation of hexadecimal program addresses to
validity and portability of
filenames and their DOS 8.3 equivalents
files
access modes, changing (chmod)
accessing multiple with vi
byte, word, and line counts, displaying (wc)
checksums, calculating for (sum)
classification of (file command)
columnar output, formatting in
comparing lines with comm
comparing with cmp
comparing with diff
comparing with diff3
computing CRC checksum
converting to tables for parsing
copying and outputting with dd
copying archives with cpio
copying between machines
rcp command
scp command
copying between Unix and MS-DOS partitions
copying with cp
creating or updating (touch)
crontab file
csplit command
cutting content
deleting on MS-DOS
deleting with rm
differences between
diff command
diff3 command
sdiff command
zdiff command
disabling for swapping, paging (swapoff)
display format options (hexdump)
dot files
dumping to standard output
duplicate lines, removing (uniq)
Emacs commands for
files (continued)
enabling for swapping, paging (swapon)
finding binary, source, and manpages for (whereis)
first lines, displaying with head
in reverse (tac)
last lines, displaying (tail)
linking
listing (ls)
locking (lockfile)
merging (merge)
moving or renaming with mv
MS-DOS
displaying content (mtype)
moving or renaming
renaming
tools for (mtools)
overwriting to make unrecoverable
ownership, changing (chown)
ownership, changing group (chgrp)
printing (lpr)
printing in reverse (tac)
removing columns
rename command
restoring from dump archive
reversing character order on each line
secure copying between networks (scp)
sorting (sort)
special, for sending or receiving data
split
transferring between networks with ftp
transferring between networks with sftp
filesystem buffers, writing to disk
filesystem quotas, editing
filesystem types
filesystems
checking with fsck
creating with mkfs
debugging
defined
displaying isoimage
exporting
ext2
displaying label
formatting device as
image file
ext3, creating
ISO/Joliet/HFS
managing
mounting 2nd
MS-DOS
checking for bad blocks
creating directory
displaying information about
dosfsck command
formatting device as
labels
mounting
tools for (mtools)
NFS
potential booting issues
process IDs of processes using
quota enforcement
unmounting (umount)
find command
GRUB
finger command
chfn command
pinky command
fingerd command
firewall rules
in iptables
restoring
saving with iptables
firewalls
flags
for a kernel image
format specifiers for printf and sprintf
flex (Fast Lexical Analyzer Generator) command
floppy disks
configuring (setfdprm)
fmt command
fold command
fold command (ex)
foldclose command (ex)
foldopen command (ex)
fonts
fc-cache command
fc-list command
for command (awk)
for shell keyword
form command (ftp)
formail command
format specifiers for printf and sprintf (awk)
formatting disks
floppies (fdformat)
MS-DOS (mformat)
free command
free disk space, measuring
free software
Free Software Foundation (FSF)
GNU project, ix
documentation
GPL (General Public License)
freenode IRC network, Linux channels
freenode IRC service
Freshmeat web site
fsck command
fstab file
fstest command (GRUB)
FTP (File Transfer Protocol)
rpm command options
secure transfer using ssh (sftp)
ftp command
ftpd command
ftpd daemon
function command (awk)
function overloading
function shell keyword
functions
awk
listed by group
listed by name
bash and ksh shell
bash shell, execution of
bc program
listing for source file 2nd
mathematical, ksh93 shell
functions command (ksh)
fuser command


G

Index

[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
gated routing daemon
gateways
protocols
gawk
gawk editor
gawk programming language
command-line options
coprocesses and sockets
features, listed
file inclusion
functions specific to
internationalization
octal and hexadecimal constants
positional specifier
profiling
user-defined functions
gcc (GNU Compiler Collection)
general options
linker options
pragma directives
warning options
gdb program
General Public License (GPL)
generate-rss command (yum)
gensub function (gawk)
geometry command (GRUB)
get command (ftp)
getconf command (ksh93)
getent command
getkeycodes command
getline command (awk)
getopts command
gettext tools
source code, URLs for
getty command
GhostScript
glob command (ftp)
global command (ex)
GNOME desktop
GNU
GNU Compiler Collection (gcc)
GNU project, ix
documentation for utilities
Linux commands
utilities
GNU sed
command-line options
pattern addressing, commands
GNU Zebra routing daemon
GNU/Linux
gpasswd command
GPG (GNU Privacy Guard)
decryption commands
encryption commands
key commands
signature commands
gpgsplit command
gpgv command
gpm command
gprof command
graph character class
graphical tools
grep command
bzgrep
egrep
metacharacters, pattern matching and filename expansion
pattern-matching metacharacters
regular expressions
zgrep
groff command
groff program
groffer command
group, changing for files
groupadd command
groupdel command
groupinfo command (yum)
groupinstall command (yum)
grouplist command (yum)
groupmod command
groupremove command (yum)
groups
changing group password
changing user's group ID
groups command
groupupdate command (yum)
grpck command
grpunconv command
GRUB (continued)
grub command syntax
GRUB shell
initrd option
installing
kernel
LILO, compared to
menu interface
naming conventions
root
stages
GRUB (Grand Unified Bootloader) 2nd 3rd
blocklists
boot-time kernel options
commands
blocklist
boot
bootp
cat
chainloader
cmp
color
configfile
debug
device
dhcp
displayapm
displaymem
dump
embed
find
fstest
geometry
halt
help
hide
ifconfig
impsprobe
initrd
install
ioprobe
lock
makeactive
map
md5crypt
module
modulenounzip
pager
partnew
parttype
password
pause
quit
rarp
read
reboot
rootnoverify
savedefault
serial
setkey
setup
splashimage
terminal
testload
testvbe
tftpserver
unhide
uppermem
vbeprobe
configuration file
device map
dual booting Linux and Windows NT/2000/XP
grub.conf file
gs (GhostScript) command
gsub function (awk)
gunzip command
gzexe command
gzip command


H

Index

[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
naming conventions
parameters, setting (hdparm)
partitioning with cfdisk command
under GRUB
hard links
hardware
detecting new and changed with kudzu
hardware address
changing for network interface
hardware commands
hardware running Linux
hash command
bash
ftp
ksh
hash mark (#)
.#file.revision
hdparm command
head command
help command
bash
ftp
GRUB
svn
svnadmin
svnlook
help, Emacs commands for
here document
here string
hexadecimal constants (gawk)
hexadecimals, program addresses, translation with addr2line
hexdump command
HFS (Hierarchical File System)
options for mkisofs command
hide command (ex)
hide command, GRUB
hist command (ksh) 2nd
history command
bash
CVS
ksh
svnlook
host command 2nd
host information commands
hostid command
hostname command
hostnames, translation to IP addresses
hosts.allow file
hosts.deny file
hotcopy command (svnadmin)
htdigest command
HTTP, rpm command options
hwclock command
hypertext reader (info)


I

Index

[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)
I/O options for terminals
I/O processing commands, sed editor
IANA (Internet Assigned Numbers Authority)
ICMP (Internet Control Message Protocol)
iconv command
id command
idle command (ftp)
if command (awk)
if shell keyword
ifconfig command 2nd
GRUB
ifdown command
ifup command
ifwconfig command
igawk program
image command (ftp)
image file, for ext2 filesystem
image section options
imapd command
import command
cvs
svn
impsprobe command (GRUB)
in operator (awk)
indentation, Emacs commands for
index function (awk)
indexes
generating for archive files
permuted, creating
inetd command
info command
svn
svnlook
yum
init command
CVS
processes invoked by (agetty)
telinit command
initrd
initrd command (GRUB)
inode contents, displaying (stat)
insert command (ex)
insert commands (vi)
insert mode (vi)
insmod command
install command
GRUB
yum
installation commands
int function (awk)
integer command (ksh)
Intel Multiprocessor Specification
Interactive Mail Access Protocol (IMAP) server daemon
internationalization with gawk
Internet Corporation for Assigned Names and Numbers (ICANN)
Internet relay chat (IRC), Linux users
Internet services daemon
Internet services daemon, extended (xinetd)
interprocess communication (IPC)
printing reports on
removing message queues
ioprobe command (GRUB)
IP addresses
conversion to hostnames with host
hostname translation to
searching for with whois command
ipchains
ipcrm command
ipcs command
iptables program 2nd 3rd
commands
match extensions for netfilter rules
options
rule specification parameters
target extensions
targets
iptables-restore command
iptables-save command
ISO 8601 date format
ISO9660 images
contents, displaying
information about, displaying
integrity, verifying
size, displaying
ISO9660/Joliet/HFS filesystem
isodump command
isoimage contents, displaying
isoinfo command
isosize command
isovfy command
ispell command
iwlist command


J

Index

[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]

JAZ drives
JFS (Journaled Filesystem)
job control, bash and ksh
commands
jobs
deleting queued jobs
executing at specified time with at
executing with anacron
listing pending jobs
queued by at command, executing
jobs command 2nd
join command
join command (ex)
Journaled Filesystem (JFS)
Joy, Bill
jumps command (ex)


K

Index

[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
kernel image
changing values in
loading with GRUB
setting flags for
kernels
boot-time options
controlling messages with klogd
examining or modifying (sysctl)
loading specified module
managing
module object-file, information about
scancode-to-keycode mapping table, viewing
slab cache information, displaying
unloading modules
video configuration (vidmode)
kernelversion command
keybindings for the less command
keyboard mapping, GRUB
keyboards
driver translation tables, listing
modes, setting
rate, setting
starting/stopping Unicode mode
keycodes
displaying (showkey)
kernel scancode to keycode mapping
setting
keymaps, loading
keyword substitutions
keywords (CVS)
date
keywords (expr)
kill and yank (Emacs)
kill command 2nd 3rd
Emacs
killall command
killall5 command
klogd command
Korn, David
kserver command (CVS)
ksh (Korn shell) 2nd
arithmetic expressions
built-in mathematical functions
built-in commands
command execution
command history
features
functions
invoking
arguments
common options
job control
ksh88 and ksh93 versions
setting restrictions on
syntax
command forms
coprocesses
filename metacharacters
quoting
redirection
startup files
variables
arrays
built-in
discipline functions
other
special prompt strings
kudzu command


L

Index

[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)
labels
MS-DOS filesystem
languages
locale-specific date and time formats
translating with gettext
last command
lastb command
lastlog command
lcd command (ftp)
ld (link editor)
ldconfig command
ldd command
led flag settings
left command (ex)
length function (awk)
less program
bzless command
commands
keybindings, configuring (lesskey)
prompts
let command 2nd
lex command
flex command
lftp program
commands
lftpget command
licenses
LILO (Linux Loader) 2nd 3rd
boot-time kernel options
compared to GRUB
configuration file
dual-booting Linux and Windows NT/2000/XP
global options
image options
initrd option
kernel options
lilo command
options
lilo command
lilo.conf file
line information commands (sed)
line numbering, vi editor
line numbers (addr2line)
line printer device parameters
line-edit mode
lines, breaking at exact width
link command
link editor (ld)
archive file maintenance
linker options, gcc
links, printing contents of symbolic link file
Linux User Groups (LUGs)
Linux, ix
advantages of
commands
distributions and support
online support
periodicals
sources and licenses
web sites devoted to
list command
ex
svn
yum
list-dblogs command (svnadmin)
list-unused-dblogs command (svnadmin)
ln command
load average for system, displaying
load command (svnadmin)
loadkeys command
Loadlin 2nd
initrd option
local command
bash
locale command
locale-specific dates and times
localinstall command (yum)
localizing gawk programs
localupdate command (yum)
locate command
slocate
lock command (GRUB)
lockfile command
log command
cvs
svn
svnlook
log function (awk)
log message for source code changes
logged-in users, showing for system
logger command
logical operators
expr command
login command
CVS
ksh
login shells, changing (chsh)
logins
bad login attempts (lastb)
last
last login times for system accounts
remote
logname command
LOGNAME environment variable
logout command
bash
CVS
logrotate program
configuration commands
look command
loop devices, setting up (losetup)
losetup command
lost+found directory
lower character class
lpadmin command
lpinfo command
lpmove command
lpq command
lpr command
lprm command
lpstat command
ls command 2nd
ftp
setting color options
lsattr command
lshift function (gawk)
lsmod command
lspci command
lstxns command (svnadmin)
lsusb command


M

Index

[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
MAC (Media Access Control) address
changing for network interface
macdef command (ftp)
machine architecture, identifying
machine uptime status, tracking (ruptime)
Macintosh, HFS (Hierarchical File System) 2nd
macro commands (Emacs)
macros
listing for source file 2nd
processor for C
RPM package spec file
vi editor
magnetic tape drive, controlling
mail commands
audiosend
biff
fetchmail
imapd
listing all messages in sendmail queue (mailq)
mail utility
command-line options
command-mode commands
compose-mode commands
configuration options
mailto
metamail
metasend
mimencode
newaliases
rmail
sendmail
sendmail statistics (mailstats)
mail filtering, formail command
mail transfer agent (MTA)
make command
description-file lines
functions
internal macros
macro modifiers
macro string substitution
pattern rules
special target names
makeactive command (GRUB)
makecache command (yum)
makedbm command 2nd
Makefiles
creating with automake
updating files with install
makemap command
man command
man pages
map command (ex)
map command (GRUB)
maps (NIS)
mark (Emacs)
mark command (ex)
marking positions in vi editor
marks command (ex)
masquerading
master boot record (MBR)
defined
pre-Linux Windows version, restoring
match function (awk)
math
bc program, library functions
mathematical functions (ksh93)
mattrib command
Maximum Transmission Unit (MTU)
mcat command
mcd command
mcopy command
MD5 checksums, computing or checking
md5crypt command (GRUB)
mdel command
mdelete command (ftp)
mdeltree command
mdir command
ftp
mdu command
Media Access Control (MAC) addresses
media commands
memory information, displaying (vmstat)
memory maps, displaying for a process
memory usage information
merge command
svn
merged changes in files
merging data stored in text-based file formats
merging documents in source code management
mesg command
messages
system control, displaying
Meta-key commands (Emacs) 2nd
Meta-key handling for virtual terminal
metacharacters
bash and ksh filenames
pattern matching
filename expansion vs.
listed by program
replacement patterns
search patterns
search-and-replace in ex and sed
metadata, versioned
metamail command
richtext, displaying
metasend command
mformat command
mget command (ftp)
MIDI files
playing with aplaymidi
raw, reading and writing
recording using ALSA
MIME types
mailto command
metamail command
metasend command
richtext, displaying
mimencode command
minfo command
mirror command (lftp)
miscellaneous commands
system administration
vi editor
mixers
audio mixer tool
command-line ALSA mixer
mkdir command
ftp
svn
mkdosfs command
mke2fs command
mkexrc command (ex)
mkfifo command
mkfs command
mkfs.ext3 command
mkisofs command
mklost+found command
mkmanifest command
mknod command
mkraid command
mkswap command
mktemp command
mktime function (gawk)
mlabel command
mls command (ftp)
mmd command
mmount command
mmove command
mode command (ftp)
modes
Emacs editor
vi editor
vim editor
modinfo command
modprobe command
depmod and
modtime command (ftp)
module command (GRUB)
modulenounzip command (GRUB)
modules
creating dependency file for
listing all loaded
loading (insmod)
loading into kernel
loading with initrd
unloading from the kernel
monotone (source code management system)
Moolenaar, Bram
more program
bzmore command
mount command 2nd
mountd command
mountd daemon 2nd
mouse, gpm command
move command (ex)
movement commands, vi editor
characters
line numbering
lines
marks
screens
searches
text
mpartition command
mpg123 command
mpg321 command
mput command (ftp)
mrd command
mren command
MS-DOS
bad blocks, checking for
changing directories on
changing file attributes (mattrib)
checking filesystem with dosfsck
copying files to or from Unix partitions
creating directories
creating filesystems with mkfs
deleting a directory
deleting file or file tree
directory contents, listing (mdir)
disk usage, displaying
displaying file content (mtype)
displaying filesystem information (minfo)
files and filesystems, tools for
filesystem label
formatting blank disk
formatting device as MS-DOS filesystem
mounting a filesystem
moving or renaming file or directory
partition, creating
renaming file or directory
mshowfat command
mt command
MTA (mail transfer agent)
mtools commands
mtoolstest command
MTU (Maximum Transmission Unit)
mtype command
Multiboot Specification
multiline input processing commands (sed)
multiple redirection
mv command
mzip command


N

Index

[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 service
name( ) function, bash and ksh
named command
named daemon 2nd
named pipes (FIFOs), creating 2nd
namei command
nameif command
nameref command (ksh93)
nameservers
nawk programming language
ncurses
mixer tool (alsamixer)
mixer tool (aumix)
netfilter 2nd
netstat command 2nd 3rd
network administration
NFS and NIS administration
TCP/IP troubleshooting
network administration tools
network interfaces
assigning address or configuring parameters
attaching serial lines as
providing to finger program
network layers, choice with Subversion
networking
commands
overview
Subversion and
networks
file transfers between
status messaging (rwhod)
new command (ex)
newaliases command
newer command (ftp)
newgrp command
newsgroups, Linux-related
newusers command
next command (awk)
next command (ex)
nextfile command (awk)
NFS (Network File System)
administration
NFS/NIS commands
domainname
makedbm
mountd
portmap
rpcinfo
showmount
ypbind
ypcat
ypinit
ypmatch
yppasswd
yppasswdd command
yppoll
yppush
ypserv
ypset
yptest
ypwhich
ypxfr
nfsd command
nfsd daemons
nfsstat command
nice command
NIS (Network Information System)
administration 2nd
clients, setting up
domains
map manipulation utilities
maps
servers
servers, setting up
user accounts
nlist command (ftp)
nm command
nmap command (ftp)
nohlsearch command (ex)
nohup command
ksh
nroff program
output, handling
nslookup command
nslookup command (deprecated)
nsupdate command
ntrans command (ftp)
null command (:)
number command (ex)
numbers, base conversions using bc
numbers, factoring
nvi text editor


O

Index

[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
object files
displaying profile data
generating from assembly language
removing symbols
size
objects
including in mail messages
octal constants (gawk)
od command
online documentation
online reference manuals, displaying information from
only command (ex)
open command (ex)
open command, ftp
open source software
OpenPGP
checking signature of files
splitting messages into packets
OpenSSH
openvt command
operators
arithmetic, bash and ksh shells
awk programming language
bc program
expr command
option argument syntax
options to Linux commands
or function (gawk)
output redirections, awk and gawk
output-formatting commands
fmt
fold
overlapping changes in files


P

Index

[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 management, rpm command
package managers 2nd 3rd
apt command
Debian
RPM (Red Hat Package Manager)
synaptic
up2date
yum (Yellow Dog updater modified)
pager command (GRUB)
paginated text files
paging commands
less
more
zless
zmore
paging, turning off/on for files
PalmOS devices
connecting to
executing DLP commands
paragraphs, Emacs commands for
partitions, disk
creating MS-DOS partition
fdisk command
GRUB partnew command
GRUB unhide command
GRUP parttype command
treated as devices
passwd command
passwd file
passwords
chpasswd command
converting unshadowed to shadowed
expiration information (chage command)
group, changing
group, shadowed file for
GRUB
information displayed by finger, changing
removing errors from passwd and shadow files
yppasswd command
yppasswdd command
paste command
patch command
pathchk command
pathname, printing with dirname
pathnames
following to terminal point
listing for files executed if command had been run
paths
basename command
to manual pages
tracepath command
pattern matching
searching with (examples)
transposing words in sed
patterns
awk
shell command execution
patterns, extglob option in bash and ksh
pause command (GRUB)
PCI (Peripheral Component Interconnect) devices, listing
PCMCIA sockets
card daemon
controlling with cardctl command
PDF (Portable Document Format) language, GhostScript interpreter
pending jobs, listing
Peripheral Component Interconnect (PCI) devices, listing
perl command
permissions, changing for files
permuted indexes
pgawk program
pidof command
ping command 2nd
pinky command
pmap command
PNM (Portable aNyMap) format
point (Emacs cursor)
popd command (bash) 2nd
portmap command
portmap daemon (RPC) 2nd
positional specifier (gawk)
POSIX
distinction between "special" built-in commands and nonspecial
pattern-matching metacharacters
PostScript language, GhostScript interpreter
poweroff command
PPP (Point-to-Point Protocol) 2nd
pppd command 2nd
pr command
praliases command
precision format specifier (printf and sprintf)
preprocessor, C language
preserve command (ex)
previous command (ex)
print character class
print command
awk
ex
ksh
printenv command
printf command
awk
format specifiers
bash and ksh93
printing commands 2nd
banner
checking print spool queue (lpq)
cupsd
disable
enable
line printer parameters, controlling (tunelp)
lpadmin
lpinfo
lpmove
print queue status, showing (lpstat)
reject
removing jobs from the queue (lprm)
sending files to be printed (lpr)
tac
tail
tailf
procedures, awk
process IDs, getting with fuser
process management commands
processes
CPU usage
displaying memory map of
killing
killing by command name
pending jobs, listing
reporting on active
resetting priority with snice
running, controlling scheduling priority
scheduling properties, changing
sending signal to or resetting priority with skill
profile data for object file
profile files 2nd
profiling (gawk)
program addresses, translation with addr2line
program maintenance commands
programmable completion (bash)
programming commands
programming languages
gcc compiler
source files, examining with ctags
programs, listing required libraries for (ldd)
prompt command (ftp)
prompt strings, special (bash and ksh)
propdel command (svn)
propedit command (svn)
properties, Subversion files
propget command (svn)
propget command (svnlook)
proplist command (svn)
proplist command (svnlook)
propset command (svn)
provides command (yum)
proxy command (ftp)
ps command
format and sort specifiers
PS1-PS4 variables
pserver command (CVS)
pseudonyms (links) for files
ptx command
punct character class
pushd command (bash) 2nd
put command (ex)
put command, ftp
putting commands (sed)
pwck command
pwconv command
pwd command
bash and ksh
ftp
python command


Q

Index

[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)
Q command (sed)
qall command (ex)
quit command
ex
ftp
GRUB
quota command
quotacheck command
quotaoff command
quotaon command
quotas
setquota command
warnquota command
quotas for specified filesystem, reporting on
quotastats command
quote command (ftp)
quoting
bash and ksh shells
quoting special characters in bash and ksh shells


R

Index

[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 (ksh)
r command (sed)
R command (sed)
RAID array devices, setting up
raidstart command
RAM disks, configuring support for
ramsize command
rand function (awk)
ranlib command
rannotate command (CVS)
RARP (Reverse Address Resolution Protocol) 2nd
rarpd command
rcp command
RCS (Revision Control System)
rdate command
rdev command
rdiff command (CVS)
rdist command
rdistd command
read command
bash and ksh
GRUB
read command (ex)
readcd command
readelf command
readlink command
readonly command
reboot command
GRUB
recent logins, displaying
recording sound using ALSA
recover command
ex
svnadmin
recv command (ftp)
Red Hat Linux, kudzu command
Red Hat Network Notification Tool (rhn-applet)
Red Hat Update Agent (up2date)
redirect command (ksh93)
redirection syntax, bash and ksh
multiple redirection
redirection using file descriptors
simple redirection
redirections
awk and gawk
redo command (ex)
reference manuals, displaying information with man
referencing arrays
reget command (ftp)
regions, Emacs commands for
regular expressions
awk escape sequences
egrep command
expr command
extended, use by GNU sed
find command
flex command
for sed command addresses
grep command 2nd
searching with (examples)
Reiser FS (Reiser Filesystem)
reject command
relational operators
bc program
expr command
release command (CVS)
remote access with svnserve
remote file distribution
client program
server, starting
remotehelp command (ftp)
remotestatus command (ftp)
removable media, ejecting
remove command
CVS
yum
rename command
ftp
renice command 2nd
Replace
replacement patterns
metacharacters for ed, ex, vi, and sed
replacing text, metacharacters for
repositories
associated with channels
converting from CVS to Subversion
source code management systems
Subversion
svnadmin administrative tool
svnlook tool, examining with
repository
reset command
ftp
resize command (ex)
resize2fs command
resolved command (svn)
resolver
restart command (ftp)
restore command
restricted shells
return command
awk
bash and ksh
rev command
Reverse Address Resolution Protocol (RARP)
GRUB rarp command
reverse-order printing of files (tac)
revert command (svn)
Revision Control System (RCS)
revision keywords for svn --revision option
rewind command (ex)
rexec command
rexecd command
RFC 1123 time format
RFC 822 time format
rhn-applet
richtext command
right command (ex)
rlog command (CVS)
rlogin command
rlogind command
rm command
rmail command
rmdir command
ftp
rmmod command
rmtxns command (svnadmin)
rndc command
root command (GRUB)
root directory for command
root filesystem, showing in /etc/mtab syntax
rootflags command
rootnoverify command (GRUB)
rotating logfiles
route command 2nd
routed command
routed daemon
routes
tracing
routing
daemons
traceroute command
routing tables
RPC (Remote Procedure Call)
querying statd for system status on hosts
rpcgen command
rpcinfo command
RPM (Red Hat Package Manager) 2nd
managing packages with up2date
managing packages with yum
package concepts
rpm command
rpmbuild command
rpm command 2nd 3rd 4th
database rebuild options
downloading packages off the internet
examples
FTP/HTTP options
general options
information selection options
install, upgrade, and freshen options
package selection options
query options
signature check options
uninstall options
verify options
rpmbuild command 2nd 3rd
rpmrc file
rsh command
rshd command
rshift function (gawk)
rsync command
rtag command (CVS)
runique command (ftp)
runlevel command
runlevels
changing (telinit)
rup command
ruptime command
rusers command
rusersd command
rwall command
rwho command
rwhod command


S

Index

[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)
Samba file and print server
sandbox 2nd
sane-find-scanner command
savedefault command (GRUB)
sbnext command (ex)
sbuffer command (ex)
scanadf command
scanimage command
Scanner Access Now Easy (SANE)
scanadf command
SCCS (Source Code Control System)
scheduling priority of running processes
scheduling properties of a process, changing
scheme command
scp command
screen command
keybindings
options
screens
vi editor movement commands
script command
scripts, RPM package spec file
SCSI and USB scanners, locating
sdiff command
search command (yum)
search commands
Emacs
fgrep (file searching)
grep
locate
look
zgrep
search patterns, metacharacters in
searching
pattern matching
regular expressions, using
search-and-replace examples, ex and sed
vi editor movement commands
Second Extended (ext2) filesystem
Secure DNS
signing secure keyset
signing zonefile
Secure DNS (DNSSEC) keys for domain name
security
firewalls
GRUB configuration file and
ssh
security commands
sed and gawk
sed command
sed editor
command-line syntax
GNU sed options
standard options
commands
alphabetical summary
basic editing
branching
I/O processing
line information
multiline input processing
syntax
yanking and putting
metacharacters in replacement patterns
operation of
pattern-matching metacharacters
search-and-replace examples
searching with regular expressions
transposing words, using pattern matching
typical uses
select shell keyword
send command (ftp)
sendmail command
command-line flags
configuration options
support files
sendmail, creating database maps for
sendport command (ftp)
sensors command
seq command
serial command (GRUB)
Serial Line IP (SLIP)
serial-lines, attaching as network interfaces (slattach)
server command (CVS)
set command
bash and ksh
ex
lftp
setfdprm command
setkeycodes command
setleds command
setlog command (svnadmin)
setmetamode command
setquota command
setsid command
setterm command
setup command (GRUB)
sftp command
sh (shell) command
sha1sum command
shadowed group file for passwords
shared libraries required by programs
shell command (ex)
shell functions
shell programming commands
shell variables
bash and ksh shells
built-in
other
CVSROOT files
shells
bash
creating for user (su)
DLP (Desktop Link Protocol)
Emacs special shell characters
ksh
login shell, changing
restricted
substituting environment variables
shift command
shopt command (bash)
showkey command
showmount command 2nd
shred command
shutdown command
sync command and
sin function (awk)
site command (ftp)
size command
ftp
skill command
slabtop command
slattach command
sleep command
ksh93
usleep
SLIP (Serial Line IP)
slocate command
SMTP (Simple Mail Transport Protocol)
snext command (ex)
snice command
SNMP (Simple Network Management Protocol)
sockets
gawk, for coproceses
soft (symbolic) links
sort command
sound cards
advanced configuration with alsactl
command-line ALSA mixer
raw MIDI files, reading/writing
sound files
CDDA, converting to WAV
Compact Disc audio files, recording in different formats
MIDI, playing with aplaymidi
playing with aplay
recording MIDI files, using ALSA
recording using ALSA
sound, Enlightened Sound Daemon
Source Code Control System (SCCS)
source code for Linux
source code management systems
Arch
CSSC
CVS
monotone
RCS
SCSS
Subversion
terminology
usage models
source command (bash)
source command (ex)
source files
examining with ctags
SourceForge web site
space character class
spacing and syntax
spec file, RPM packages
special files (capable of sending or receiving data)
spellchecking, ispell command
splashimage command (GRUB)
split command (ex)
split function (awk)
sprevious command (ex)
sprintf function (awk)
format specifiers
sqrt function (awk)
srand function (awk)
ssh command
environment variables
escape characters
files
options
ssh-add command
ssh-agent command
ssh-keygen command
ssh-keyscan command
sshd command
stable releases (Subversion)
Stallman, Richard
stat command
statd command
status command
CVS
ftp
svn
status-line commands, vi editor
stickiness
stop command
ex
ksh (Korn shell)
storage commands
strace command
strfile command
strftime function (gawk)
string searches with apropos
strings command
strings, printing using specified formats (printf)
strip command
strtonum function (gawk)
strtonum( ) function
struct command (ftp)
stty command (bash and ksh)
stty tostop command
su command
sub function (awk)
subdomains
substitute command (ex)
substr function (awk)
Subversion 2nd 3rd 4th
conceptual overview
converting CVS repository to
copy, modify, merge model
features
future releases
obtaining
other components
releases
source code
special file properties
svn command-line client
svn subcommands
svnadmin, repository administration with
svnlook, examining repository with
svnserve, providing remote access
using for version control
sudo command
sunique command (ftp)
support
suspend command
bash and ksh
suspend command (ex)
sview command (ex)
svn
subcommands
svnadmin
options
subcommands
svndumpfilter command
svnlook
svnserve
swapoff command
swapon command
swapspace, creating
switch command (svn)
symbolic links
printing contents of symbolic link file
symbols, removing from object files
synaptic command
sync command
sysctl command
sysklogd command
syslogd command
system
information, displaying (uname)
initializing
logged-in users, displaying (who)
system administration commands
agetty
filesystem, managing
kernel, managing
miscellaneous
networking
printing
security and system integrity
system activity and process management
users
system command (ftp)
system control messages, displaying
system function (awk)
system ID, setting
system status commands
displaying uptime
load average, displaying (tload)
top
usage information, displaying (w)
system tools
System V
killall5 command
ptx -G command
systime function (gawk)


T

Index

[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)
t command (sed)
T command (sed)
tabs, converting whitespace to
tac command
tag 2nd
tag command (CVS)
tag command (ex)
tags command (ex)
tags, efficient tagging with Subversion
tail command
tailf command
talk command
tar command
taskset command
tbl program, output, handling
TCP/IP 2nd
administrative commands
arp command
configuring
dnsdomainname command
fingerd command
ftpd command
gateways and routing
ifconfig command
imapd command
included protocols
inetd command
IP addresses
logger command
name service
named command
netstat command
rdate command
rexecd command
rlogind command
rmail command
rndc command
route command
routed command
rup command
ruptime command
rusers command
rwall command
rwhod command
slattach command
talkd command
tcpd command
telnetd command
tftpd command
tracepath command
traceroute command
troubleshooting
xinetd command
tcpd command
tcpdump command 2nd
tcpslice command
tcsh (enhanced C shell)
tee command
telinit command
telnet command
telnetd command
template file of C #define statements
temporary filenames, generating unique (mktemp)
tenex command (ftp)
terminal
clearing display
setting with agetty
switching to virtual terminal N
terminal emulators, ANSI/VT100 emulation, enabling (screen)
terminal sessions, recording (script)
terminals
deallocating virtual console
displaying name of (tty)
GRUB
I/O options, setting (stty)
initializing (tset)
resetting
setting attributes
stopping background jobs attempting to send output
TERM shell variable
test command 2nd
testload command (GRUB)
testvbe command (GRUB)
text
editing with vi
formatting with fmt
pattern matching
vi editor movement commands
text editors 2nd
dual mode vs. modeless editing
pattern-matching metacharacters
text files, connverting to paginated or columned version
text manipulation
text statement (bc)
text-based files, merging data in
text-processing commands
TFTP (Trivial File Transfer Protocol)
GRUB
tftp command
tftpd command
Third Extended (ext3) filesystem
time command 2nd
time zones, displaying data about
times command
tload command
tmpwatch command
tolower function (awk)
top command
top-level domains
topological sort on partially ordered strings
Torvalds, Linus
touch command
toupper function (awk)
tr (translate) command
trace command (ftp)
tracepath command
traceroute command 2nd
tracing system calls (strace)
Transaction Signatures (TSIG) keys for domain name
translations with gettext tools
transposing words, using pattern matching
transposition commands, Emacs
trap command
tree command (svnlook)
trigger scriptlets, RPM package spec file
Trivial File Transfer Protocol (TFTP)
tftpd command
troff command
true command
bash and ksh
true version history (Subversion)
trunk
tset command
tty command
tune2fs command
tunelp command
type command
bash
ftp
ksh
typeset command


U

Index

[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]

UID shell variable
ul command
ulimit command
umask command
bash and ksh
ftp
umount command 2nd
unabbreviate command (ex)
unalias command
uname command
unary operators
bash and ksh shells
bc program
uncompress command
underscores, translating to underlining
undo command (ex)
undoing commands, Emacs
unedit command (CVS)
unexpand command
unhide command (ex)
unicode_start command
unicode_stop command
uniq command
Universal Serial Bus (USB) devices, listing
Universal Unique Identifier (UUID)
Unix shell command (sh)
Unix, compared to Linux
unmap command (ex)
unset command
until shell keyword
up2date
command-line and a graphical interfaces
commands
options
up2date-config command
up2date-nox command
update command
cvs
svn
yum
upgrade command (yum)
upper character class
uppermem command (GRUB)
uptime command
USB (Universal Serial Bus) devices, listing
USB (Universal Serial Bus), locating scanners
Usenet newsgroups
user accounts, NIS
user command (ftp)
user ID, printing current
USER internal variable
useradd command
userdel command
usermod command
users
creating or updating system users
enabling mounting/unmounting of filesystems
information about, finger command
logged-in, showing for system
login name, finding
management commands
printing message to all logged into a host (rwall)
reporting on with rusers and rusersd
reporting those logged onto machines on local network
users command
usleep command
uudecode command
uuencode command
uuid command, svnlook
uuidgen command


V

Index

[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)
v command (sed)
variable substitution
PS1-PS4 variables
variables
awk, built-in
awk, value assignments
bash and korn shells
exporting
bash and ksh shell
arrays
built-in
discipline functions (ksh93)
other
special prompt strings
CVSROOT directory
declaring in bash
vbeprobe command (GRUB)
vdir command
vendor branch (CVS)
verbose command (ftp)
verify command (svnadmin)
verifying ISO9660 image
version command
CVS
ex
version-control systems
CVS
versioned metadata
VFAT filesystem
vi editor 2nd 3rd
command mode
command-line syntax
options
commands
accessing multiple files
edit commands
insert
interaction with system
macros
miscellaneous
movement
saving and exiting
status-line
syntax
user-defined, characters for 2nd
vi editor (continued)
configuration
:set command
example .exrc file
~/.exrc file
ex commands in
ex editor
insert mode
metacharacters in replacement patterns
modes
operating modes
overview
pattern-matching metacharacters
vidmode command
view command (ex)
vile text editor
vim
vim command
vim editor
visual mode
virtual consoles
number of, determining
virtual memory statistics, displaying (vmstat)
virtual terminal N, switching to
virtual terminals
deallocating and destroying
LED flag settings
Meta-key handling
openvt command
visual command (ex)
VISUAL internal variable (cvs)
visual mode (vim)
vmstat command
volname command
vsplit command (ex)


W

Index

[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
w command (sed)
W command (sed)
wait command
bash and ksh
lftp
wall command
ex editor
warnquota command
watch command
CVS
watchers command (CVS)
WAV format, converting CDDA to
wc command
whatis command
whatis database, searching with apropos
When
whence command (ksh)
whereis command
which command
while command, awk
while shell keyword
whitespace, converting to tabs (unexpand)
who command
whoami command
whois command
width format specifier (printf and sprintf)
Windows
dual booting, NT/2000/XP and Linux
windows
Emacs
Emacs buffer
Emacs commands for
Windows
FAT and VFAT filesystems
windows
vi commands for
Windows-based networking
wireless network interface, configuration commands
wlancfg command
wnext command (ex)
word character class, bash and ksh shells
word-abbreviation commands, Emacs
wq command (ex)
wqall command (ex)
write command
ex
write messages sent to your terminal by others


X

Index

[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 (XFree86), ix
xargs command
xdigit character class
XDR (eXternal Data Representation)
XFS (Extensible Filesystem)
xinetd command
xit command (ex)
xor function (gawk)


Y

Index

[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
yanking (pasting) text in Emacs
yanking and putting commands (sed)
yes command
yet another compiler-compiler (yacc)
youngest command (svnlook)
ypbind command 2nd
ypcat command
ypinit command 2nd
ypmatch command
yppasswd command
yppasswdd command
yppoll command
yppush command 2nd
ypserv command 2nd
ypset command
yptest command
ypwhich command
ypxfr command
Yum (Yellow Dog updater modified)
yum command
yum commands, summary of
yum command


Z

Index

[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)
zcat command
zcmp command
zdiff command
zdump command
zforce command
zgrep command
zic command
ZIP drives
zless command
zmore command
znew command
zonefile (secure DNS)
zsh