main

Book Cover
Unix in a Nutshell, 4th Edition
By Arnold Robbins
...............................................
Publisher: O'Reilly
Pub Date: October 2005
ISBN: 0-596-10029-9
Pages: 906

Table of Contents | Index
Overview

As an open operating system, Unix can be improved on by anyone and everyone: individuals, companies, universities, and more. As a result, the very nature of Unix has been altered over the years by numerous extensions formulated in an assortment of versions. Today, Unix encompasses everything from Sun's Solaris to Apple's Mac OS X and more varieties of Linux than you can easily name.

The latest edition of this bestselling reference brings Unix into the 21st century. It's been reworked to keep current with the broader state of Unix in today's world and highlight the strengths of this operating system in all its various flavors.

Detailing all Unix commands and options, the informative guide provides generous descriptions and examples that put those commands in context. Here are some of the new features you'll find in Unix in a Nutshell, Fourth Edition:

  • Solaris 10, the latest version of the SVR4-based operating system, GNU/Linux, and Mac OS X

  • Bash shell (along with the 1988 and 1993 versions of ksh)

  • tsch shell (instead of the original Berkeley csh)

  • Package management programs, used for program installation on popular GNU/Linux systems, Solaris and Mac OS X

  • GNU Emacs Version 21

  • Introduction to source code management systems

  • Concurrent versions system

  • Subversion version control system

  • GDB debugger

As Unix has progressed, certain commands that were once critical have fallen into disuse. To that end, the book has also dropped material that is no longer relevant, keeping it taut and current.

If you're a Unix user or programmer, you'll recognize the value of this complete, up-to-date Unix reference. With chapter overviews, specific examples, and detailed command.


Table of Contents

Book Cover
Unix in a Nutshell, 4th Edition
By Arnold Robbins
...............................................
Publisher: O'Reilly
Pub Date: October 2005
ISBN: 0-596-10029-9
Pages: 906

Table of Contents | Index

Copyright
Dedication
Preface
 | Audience
 | Scope of This Book
 | Conventions
 | Using Code Examples
 | Safari® Enabled
 | How to Contact Us
 | Acknowledgments
Part I: Commands and Shells
 | Chapter 1. Introduction
 |  | Section 1.1. Unix in the 21st Century
 |  | Section 1.2. Obtaining Compilers
 |  | Section 1.3. Building Software
 |  | Section 1.4. What's in the Quick Reference
 |  | Section 1.5. Beginner's Guide
 |  | Section 1.6. Solaris: Standard Compliant Programs
 | Chapter 2. Unix Commands
 |  | Section 2.1. Introduction
 |  | Section 2.2. Alphabetical Summary of Common Commands
 |  | Section 2.3. Alphabetical Summary of Solaris Commands
 |  | Section 2.4. Alphabetical Summary of GNU/Linux Commands
 |  | Section 2.5. Alphabetical Summary of Mac OS X Commands
 |  | Section 2.6. Alphabetical Summary of Java Commands
 | Chapter 3. The Unix Shell: An Overview
 |  | Section 3.1. Introduction to the Shell
 |  | Section 3.2. Purpose of the Shell
 |  | Section 3.3. Shell Flavors
 |  | Section 3.4. Shell Source Code URLs
 |  | Section 3.5. Common Features
 |  | Section 3.6. Differing Features
 | Chapter 4. The Bash and Korn Shells
 |  | Section 4.1. Overview of Features
 |  | Section 4.2. Invoking the Shell
 |  | Section 4.3. Syntax
 |  | Section 4.4. Functions
 |  | Section 4.5. Variables
 |  | Section 4.6. Arithmetic Expressions
 |  | Section 4.7. Command History
 |  | Section 4.8. Job Control
 |  | Section 4.9. Command Execution
 |  | Section 4.10. Restricted Shells
 |  | Section 4.11. Built-in Commands (Bash and Korn Shells)
 | Chapter 5. tcsh: An Extended C Shell
 |  | Section 5.1. Overview of Features
 |  | Section 5.2. Invoking the Shell
 |  | Section 5.3. Syntax
 |  | Section 5.4. Variables
 |  | Section 5.5. Expressions
 |  | Section 5.6. Command History
 |  | Section 5.7. Command-Line Manipulation
 |  | Section 5.8. Job Control
 |  | Section 5.9. Built-in Commands
 | Chapter 6. Package Management
 |  | Section 6.1. Linux Package Management
 |  | Section 6.2. The Red Hat Package Manager
 |  | Section 6.3. Yum: Yellowdog Updater Modified
 |  | Section 6.4. up2date: Red Hat Update Agent
 |  | Section 6.5. The Debian Package Manager
 |  | Section 6.6. Mac OS X Package Management
 |  | Section 6.7. Solaris Package Management
Part II: Text Editing and Processing
 | Chapter 7. Pattern Matching
 |  | Section 7.1. Filenames Versus Patterns
 |  | Section 7.2. Metacharacters
 |  | Section 7.3. Metacharacters, Listed by Unix 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 awk 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.12. Output Redirections
 |  | Section 11.13. Source Code
Part III: Software Development
 | Chapter 12. Source Code Management: An Overview
 |  | Section 12.1. Introduction and Terminology
 |  | Section 12.2. Usage Models
 |  | Section 12.3. Unix Source Code Management Systems
 |  | Section 12.4. Other Source Code Management Systems
 | Chapter 13. The Revision Control System
 |  | Section 13.1. Overview of Commands
 |  | Section 13.2. Basic Operation
 |  | Section 13.3. General RCS Specifications
 |  | Section 13.4. Alphabetical Summary of Commands
 | Chapter 14. The Concurrent Versions System
 |  | Section 14.1. Conceptual Overview
 |  | Section 14.2. Command-Line Syntax and Options
 |  | Section 14.3. Dot Files
 |  | Section 14.4. Environment Variables
 |  | Section 14.5. Keywords and Keyword Modes
 |  | Section 14.6. Dates
 |  | Section 14.7. CVSROOT Variables
 |  | Section 14.8. Alphabetical Summary of Commands
 | Chapter 15. The Subversion Version Control System
 |  | Section 15.1. Conceptual Overview
 |  | Section 15.2. Obtaining Subversion
 |  | Section 15.3. Using Subversion: A Quick Tour
 |  | Section 15.4. The Subversion Command Line Client: svn
 |  | Section 15.5. Repository Administration: svnadmin
 |  | Section 15.6. Examining the Repository: svnlook
 |  | Section 15.7. Providing Remote Access: svnserve
 |  | Section 15.8. Other Subversion Components
 | Chapter 16. The GNU make Utility
 |  | Section 16.1. Conceptual Overview
 |  | Section 16.2. Command-Line Syntax
 |  | Section 16.3. Makefile Lines
 |  | Section 16.4. Macros
 |  | Section 16.5. Special Target Names
 |  | Section 16.6. Writing Command Lines
 | Chapter 17. The GDB Debugger
 |  | Section 17.1. Conceptual Overview
 |  | Section 17.2. Command-Line Syntax
 |  | Section 17.3. Initialization Files
 |  | Section 17.4. GDB Expressions
 |  | Section 17.5. The GDB Text User Interface
 |  | Section 17.6. Group Listing of GDB Commands
 |  | Section 17.7. Summary of set and show Commands
 |  | Section 17.8. Summary of the info Command
 |  | Section 17.9. Alphabetical Summary of GDB Commands
 | Chapter 18. Writing Manual Pages
 |  | Section 18.1. Introduction
 |  | Section 18.2. Overview of nroff/troff
 |  | Section 18.3. Alphabetical Summary of man Macros
 |  | Section 18.4. Predefined Strings
 |  | Section 18.5. Internal Names
 |  | Section 18.6. Sample Document
Part IV: Commands and Shells
 | Appendix A. ISO 8859-1 (Latin-1) Character Set
 | Bibliography
 |  | Unix Descriptions and Programmer's Manuals
 |  | Unix Internals
 |  | System and Network Administration
 |  | Programming with the Unix Mindset
 |  | Programming Languages
 |  | TCP/IP Networking
 |  | Software Development
 |  | Emacs
 |  | Standards
 |  | O'Reilly Books
About the Author
Colophon
Index


Chapter 1. Introduction

The Unix operating system originated at AT&T Bell Labs in the early 1970s. System V Release 4 (SVR4) came from USL (Unix System Laboratories) in the late 1980s. Unix source ownership is currently a matter of litigation in U.S. courts. Because Unix was able to run on different hardware from different vendors, developers were encouraged to modify Unix and distribute it as their own value-added version. Separate Unix traditions evolved as a result: USL's System V, the Berkeley Software Distribution (BSD, from the University of California, Berkeley), Xenix, etc.

SVR4, which was developed jointly by USL (then a division of AT&T) and Sun Microsystems, merged features from BSD and SVR3. This added about two dozen BSD commands (plus some new SVR4 commands) to the basic Unix command set. In addition, SVR4 provided a BSD Compatibility Package, a kind of "second string" command group. This package included some of the most fundamental BSD commands, and its purpose was to help users of BSD-derived systems make the transition to SVR4.


1.1. Unix in the 21st Century

Today, the specification of what makes a system "Unix" is embodied primarily in the POSIX standard, an international standard based on System V and BSD. Commercial Unix systems, such as Solaris from Sun Microsystems, AIX from IBM, and HP-UX from Hewlett Packard, are standard-adhering direct descendants of the original Unix systems.

A number of other systems are "spiritual" descendents of Unix, even though they contain none of the original Unix source code. The most notable of these systems is GNU/Linux, which has seen a meteoric rise in popularity. However, a large number of systems derived from the 4.4-BSD-Lite distribution are also popular. All of these systems offer standards compliance and compatibility with SVR4 and earlier versions of BSD.

This edition of Unix in a Nutshell attempts to define the cross-section of features and commands that "make a Unix system Unix." To that end, it covers three of the most popular and representative systems now available.

Solaris 10

Solaris 10 is a distributed computing environment from Sun Microsystems. Solaris includes the SunOS 5.10 operating system, plus additional features such as the Common Desktop Environment, GNOME, and Java tools. In addition, the kernel has received significant enhancement to support multiprocessor CPUs, multithreaded processes, kernel-level threads, and dynamic loading of device drivers and other kernel modules. Most of the user-level (and system administration) content comes from SVR4. As a result, Solaris 10 is based on SVR4 but contains additional BSD/SunOS features. To help in the transition from the old (largely BSD-based) SunOS, Solaris provides the BSD/SunOS Compatibility Package and the Binary Compatibility Package.

Sun has made binary versions of Solaris for the SPARC and Intel architectures available for "free," for noncommercial use. You pay only for the media, shipping, and handling, or you may download installation CD images. To find out more, see http://www.sun.com/developer.

As this book was going to press, Sun announced that it would be making the source code for Solaris available as Open Source. For more details, see http://www.opensolaris.org.

Fedora GNU/Linux

There are many distributions of GNU/Linux (the combination of the GNU utilities with the Linux kernel to make a complete operating environment). We have chosen the Fedora Core 3 system from Red Hat, Inc.[*] To find out more, see http://fedora.redhat.com.

[*] This is undoubtedly cause to receive hate-mail from the advocates of other distributions. In our defense, we can only claim that it's impossible to cover every GNU/Linux distribution, and that for everyday use with a shell prompt, the systems are all extremely similar.

Mac OS X 10.4 (Tiger)

Mac OS X introduced a revolution into the Macintosh world, with a slick new interface (Aqua) running atop a powerful OS kernel based on Mach and FreeBSD. The shell level utilities are largely from FreeBSD. The 10.4 (a.k.a. "Tiger") release is current as of this writing. To find out more, see http://www.apple.com/macosx.

One important "quirk" of Mac OS X is worth noting. The default HPFS filesystem stores filenames in their original case, but it ignores case when looking for files. In practice, this make surprisingly little difference. However, it can occasionally have weird side effects, since things like command completion in the Bash shell are still case-sensitive.


1.2. Obtaining Compilers

If you wish to build programs from source code, you need a compiler. Almost all Unix applications are written in C or C++, with the majority still written in C. This section describes obtaining compilers for the three systems covered in this book.

1.2.1. Solaris

Solaris 10 includes a Java compiler. Earlier versions of Solaris did not come with C or C++ compilers. You had to either buy compilers from Sun, from other third party vendors, or find a binary of some version of GCC for use in bootstrapping the latest version of GCC.

The final version of Solaris 10 now includes GCC (both C and C++ compilers) in /usr/sfw/bin. This is true for both the SPARC and Intel x86 versions. You thus have a choice: you may use the supplied GCC, or buy high-quality C and C++ compilers from Sun.

Besides GCC, a very large number of precompiled packages is available from http://www.sunfreeware.com/. You should see both the "Download/Install" and "FAQ" sections of that web site.

All the software from http://www.sunfreeware.com is in pkgadd format and is installable using that command. (See Chapter 6.) We recommend reading the details on the web site, which will always be up to date.

Note that many commands discussed in this book won't be on your system if all you've done is an end user install. If you can afford the disk space, do at least a developer install. This also installs many of the header files and libraries that you need in order to compile programs from source code.

For support issues and publicly released patches to Solaris, the web starting point is http://sunsolve.sun.com.

1.2.2. GNU/Linux

GNU/Linux systems usually install software development tools by default. If your system does not have compiler tools or make (see Chapter 16), then you will have to find the appropriate package(s) for your distribution. This is likely to be one or more .rpm or .deb files on your distribution media (CD or DVD), or you may be able to install it over the Internet, using a package manager such as apt or yum.

At a minimum, you will need the GNU Compiler Collection (GCC), system header files and libraries, the GNU Binutils (assembler, loader, ar, etc.), and make.

1.2.3. Mac OS X

Unix-style development tools (compiler, make) are included as part of the larger Xcode Tools package . Boxed distributions of Mac OS X include an Xcode Tools CD. The easiest way to install the tools is to insert that CD into your CD drive.

If your version of Mac OS X is that which came with your hardware, you won't have an Xcode Tools CD. Instead, click on Developer.mpkg in /Applications/Installers/Developer Tools. Doing so installs the development tools.


1.3. Building Software

Many of the programs listed in Chapter 2 are available in source code form from the Internet. For GNU/Linux and Mac OS X, you may be able to use a package manager to download and install the software (see Chapter 6). Similarly, for Solaris, you may be able to get a precompiled version of the program from http://www.sunfreeware.com/.

However, it's possible, particularly on a commercial Unix system, that you will want (or need) to download the source and build the program yourself if you don't have it, or if you wish to obtain the very latest version. This section outlines the conventional build process.

Most Internet software is written in C or C++. To compile it you will need a compiler. See the previous section for a discussion of where to get a compiler if you don't have one.

Today's programs usually use the GNU Project's Autoconf software suite for managing portability issues. Autoconf generates a shell script named configure, which tests various aspects of the target system. The end result of running configure is a Makefile custom-tuned to the particular system (see Chapter 16), and a header file describing the features available, or missing, from the system. As a result, the recipe for building software is usually quite simple, consisting of the following:

  1. Download the software. This can be done with a noninteractive program such as wget or curl (see their entries in Chapter 2), or interactively using anonymous FTP for programs distributed that way.

  2. Decompress and extract the software.

  3. Change directory into the program's distribution directory.

  4. Run configure.

  5. Run make.

  6. Optionally, run the program's self-test suite.

  7. Run make install, usually as root, to install the software.

The following example uses GNU sed to illustrate the process. The steps are similar or identical for all GNU software, and for most other freely-available programs as well.

First, we obtain the program using wget:

    $ wget ftp://ftp.gnu.org/gnu/sed/sed-4.1.4.tar.gz    Retrieve the latest version

    --15:00:04--  ftp://ftp.gnu.org/gnu/sed/sed-4.1.4.tar.gz

               => 'sed-4.1.4.tar.gz'

    Resolving ftp.gnu.org... 199.232.41.7

    Connecting to ftp.gnu.org[199.232.41.7]:21... connected.

    Logging in as anonymous ... Logged in!

    ==> SYST ... done.    ==> PWD ... done.

    ==> TYPE I ... done.  ==> CWD /gnu/sed ... done.

    ==> PASV ... done.    ==> RETR sed-4.1.4.tar.gz ... done.

    Length: 794,257 (unauthoritative)

    100%[==================================>] 794,257      60.04K/s    ETA 00:00

    15:00:29 (38.86 KB/s) - 'sed-4.1.4.tar.gz' saved [794257]

The next step is to decompress and extract the software:

    $ gzip -d < sed-4.1.4.tar.gz | tar -xpvf -           Extract source code

    sed-4.1.4/

    sed-4.1.4/ABOUT-NLS

    sed-4.1.4/AUTHORS

    sed-4.1.4/BUGS

    ...

Next we change into the directory and run configure:

    $ cd sed-4.1.4                                       Change directory

    $ ./configure && make                                Run configure and make

    checking for a BSD-compatible install... /usr/bin/install -c

    checking whether build environment is sane... yes

    checking for gawk... gawk

    checking whether make sets $(MAKE)... yes

    ...

The && construct runs make only if configure finishes successfully (see Chapter 4).

Next, we run the test suite, to ensure that there were no problems:

    $ make check                                         Test the build

    Making check in intl                                Lots of output omitted

    ...

    PASS: dc

    ===================

    All 71 tests passed

    ===================

Finally, we install the software. This may require administrative privileges:

    $ su root                                            Change to superuser

    Password:                                           Password is not echoed

    # make install                                       Install GNU sed into /usr/local

    ...


1.4. What's in the Quick Reference

This guide presents the major features of Solaris, GNU/Linux, and Mac OS X. In addition, this guide presents chapters on Emacs, RCS, CVS, Subversion, GNU Make, and GDB, the GNU debugger. Although they are not part of commercial Unix systems, they are found on many Unix systems because they are useful add-ons.

But keep in mind: if your system doesn't include all the component packages, there will be commands in this book you won't find on your system.

The summary of Unix commands in Chapter 2 makes up a large part of this book. Only user/programmer commands are included; administrative commands are purposely ignored. Chapter 2 describes the following set:

  • Commands and options in Solaris, GNU/Linux, and Mac OS X. This includes many "essential" tools for which source and/or binaries are available via the Internet

  • Solaris-only tools

  • GNU/Linux-only tools

  • Mac OS X-only tools

  • Java-related tools


1.5. Beginner's Guide

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

1.5.1. Communication

ftp | Interactive file transfer program.
login | Sign on to Unix.
mailx | Read or send mail.
slogin | Sign on to remote Unix using secure shell.
ssh | Connect to another system, securely.

1.5.2. Comparisons

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

1.5.3. File Management

cd | Change directory.
chgrp | Change file group.
chmod | Change access modes on files.
chown | Change file owner.
cksum | Print a file checksum, POSIX standard algorithm.
cp | Copy files.
csplit | Break files at specific locations.
file | Determine a file's type.
head | Show the first few lines of a file.
less | A sophisticated interactive pager program for looking at information on a terminal, one screenful (or "page") at a time. The name is a pun on the more program.
ln | Create filename aliases.
locate | Find a file somewhere on the system based on its name. The program uses a database of files that is usually automatically rebuilt, nightly.
ls | List files or directories.
md5sum | Print a file checksum using the Message Digest 5 (MD5) algorithm.
mkdir | Create a directory.
more | Display files by screenful.
mv | Move or rename files or directories.
pwd | Print working directory.
rm | Remove files.
rmdir | Remove directories.
scp | Copy files to remote system securely.
split | Split files evenly.
tail | Show the last few lines of a file.
wc | Count lines, words, and characters.

1.5.4. Miscellaneous

banner | Make posters from words.
bc | Arbitrary precision calculator.
cal | Display calendar.
calendar | Check for reminders.
clear | Clear the screen.
info | The GNU Info system for online documentation.
man | Get information on a command.
nice | Reduce a job's priority.
nohup | Preserve a running job after logging out.
passwd | Set your login password.
script | Produce a transcript of your login session.
spell | Report misspelled words.
su | Switch to a different user.

1.5.5. Printing (BSD Commands)

lpr | Send to the printer.
lpq | Get printer status.
lprm | Cancel a printer request.
pr | Format and paginate for printing.

1.5.6. Printing (System V Commands)

cancel | Cancel a printer request.
lp | Send to the printer.
lpstat | Get printer status.
pr | Format and paginate for printing.

1.5.7. Programming

cc | C compiler.
ctags | C function references (for vi).
ld | Loader.
lex | Lexical analyzer generator.
make | Execute commands in a specified order.
od | Dump input in various formats.
splint | C program analyzer.
strace | Trace signals and system calls.
strip | Remove data from an object file.
truss | Trace signals and system calls.
yacc | Parser generator. Can be used with lex.

1.5.8. Searching

egrep | Extended version of grep.
fgrep | Search files for literal words.
find | Search the system for filenames matching patterns or attributes.
grep | Search files for text patterns.
strings | Display text strings found in binary files.

1.5.9. Shells

Bourne family shells:

bash | The GNU Project's Bourne Again Shell.
ksh | The Korn shell, either an original or clone, depending upon the operating system.
pdksh | The Public Domain Korn shell.
sh | The original Bourne shell, particularly on commercial Unix systems.
zsh | The Z-shell.

C shell family shells:

csh | The original BSD C shell.
tcsh | The "Tenex" C shell: a much-enhanced version of csh.

1.5.10. Shell Programming

basename | Print the last component of a pathname, optionally removing a suffix.
dirname | Print all but the last component of a pathname.
echo | Repeat command-line arguments on the output.
expr | Perform arithmetic and comparisons.
id | Print user and group ID and name information.
line | Read a line of input.
printf | Format and print command-line arguments.
sleep | Pause during processing.
test | Test a condition.

1.5.11. Storage

bunzip2 | Expand files compressed with bzip2 (.bz2 files).
bzip2 | Very high quality file compression program.
cpio | Copy archives in or out.
gunzip | Expand compressed (.gz and .Z) files.
gzcat | Display contents of compressed files (may be linked to zcat).
gzip | Compress files to free up space.
tar | File tree and tape archiver.
zcat | Display contents of compressed files.

1.5.12. System Status

at | Execute commands later.
crontab | Automate commands.
date | Display or set date.
df | Show free disk space.
du | Show disk usage.
env | Show environment variables.
finger | Display information about users.
kill | Terminate a running command.
ps | Show processes.
stty | Set or display terminal settings.
who | Show who is logged on.

1.5.13. Text Processing

awk | A pattern-matching programming language for working with text files.
cat | Concatenate files or display them.
cut | Select columns for display.
ex | Line editor underlying vi.
fmt | Produce roughly uniform line lengths.
iconv | General-purpose character-encoding conversion tool.
join | Merge different columns into a database.
paste | Merge columns or switch order.
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.
xargs | Process many arguments in manageable portions.


1.6. Solaris: Standard Compliant Programs

Where the behavior specified by the POSIX standard differs from the historical behavior provided by a command, Solaris provides a different version of the command in either /usr/xpg6/bin or in /usr/xpg4/bin. On Solaris systems, you should place these two directories into your search path before the standard /usr/bin directory. Some of these commands are not covered in this book, since they are either administrative commands or are obsolete. Also, today, it is unlikely that the commands in /usr/ucb will be useful; you probably should not have that directory in your search path.

ar | delta | file | kill | nm | tail
awk | df | find | link | nohup | tr
basename | du | get | ln | od | ulimit
bc | ed | getconf | ls | pr | vedit
chgrp | edit | getopts | m4 | rm | vi
chown | egrep | grep | make | sccs | view
cp | env | hash | more | sed | wait
ctags | ex | id | mv | sh | who
date | expr | ipcs | nice | sort | xargs
dc | fgrep | jobs | nl | stty |


2.1. Introduction

This chapter presents the Unix commands of interest to users and programmers. Most of these commands appear in the "Commands" section of the online manual. With rare exception, this book purposely avoids system administration commands, because system administration is beyond its scope. The focus instead is on everyday commands, those used both interactively and for programming.

Summarizing three operating systems that are similar but not identical is a daunting task. In order to make a coherent presentation, the chapter is organized as follows:

Common Commands

This section lists commands that should be available on just about any Unix system. We have included here many commands that are downloadable from the Internet and that are standard with GNU/Linux, such as autoconf or wget, even though they may not come "out of the box" on commercial Unix systems. Wherever possible, we provide a URL from which the source to the command may be downloaded, so that you can build the program yourself if you want it. See the section "Obtaining Compilers" in Chapter 1 for what to do if you don't have a C compiler for your system.

Additionally, we have made an effort to be as concise as possible. For example, GNU-style long options are listed side-by-side with their standard single-letter counterparts. Similarly, several commands have associated with them additional more specialized commands that are needed only rarely. We simply list such commands as "related," without giving them separate entries. For such commands, you should then see your system's online manual pages or other documentation.

Solaris Commands

This section lists the important commands that are available only on Solaris.

GNU/Linux Commands

This section lists the important commands that are available only on GNU/Linux.

Mac OS X Commands

This section lists the important commands that are available only on Mac OS X.

Java Commands

The primary commands for doing Java development. These are (essentially) the same across all systems.

Even commands that appear in the section "Alphabetical Summary of Common Commands" are not identical on all systems. Thus, here too we've made an effort to describe the common behavior first, with additional subsections on system specific behavior. This occurs most frequently for the different options that different versions of the commands accept.

In the command summaries, each entry is labeled with the command name on the left-hand edge of the page. The syntax line is followed by a brief description and a list of all 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.

Some options can be invoked only by a user with special system privileges. Such a person is often called a "superuser." This book uses the term privileged user instead.

Typographic conventions for describing command syntax are listed in the Preface. For additional help in locating commands, see the Index.

2.1.1. Finding Commands on Solaris

Solaris systems provide a number of "bin" directories underneath /usr for different kinds of commands. For example, /usr/bin holds most regular commands, /usr/java/bin has the Java commands, and so on. The bin directories are summarized in Table 2-1.

Table 2-1. Solaris bin directories

Directory

Purpose

/bin

Symbolic link to /usr/bin

/sbin

System administration commands

/usr/sbin

More system administration commands

/usr/bin

Regular commands

/usr/X/bin

X Window System utilities

/usr/ccs/bin

C Compilation System: compiler-related programs

/usr/dt/bin

Common Desktop Environment (CDE) programs

/usr/java/bin

Java programs

/usr/openwin/bin

OpenWindows programs

/usr/perl5/bin

The perl command and its related programs

/usr/sfw/bin

Additional software from the Internet

/usr/ucb

Berkeley Unix compatibility programs

/usr/xpg4/bin

Standards-compliant versions of regular utilities

/usr/xpg6/bin

More standards compliant versions of regular utilities

We strongly recommend placing /usr/xpg6/bin and /usr/xpg4/bin in your shell search path before the other directories. Solaris is unique among modern Unix systems in that the versions in /usr/bin continue to be the original System V Release 4 versions of the commands. Today, with just about every other system being POSIX compliant, you should set up your Solaris account to be POSIX compliant too! For Bash or the Korn shell, use something like this in your .profile file:

    # Use multiple lines to fit on the page:

    PATH="/usr/xpg6/bin:/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/usr/java/bin"

    PATH="$PATH:/usr/sfw/bin:/usr/perl5/bin"

    PATH="$PATH:/usr/dt/bin:/usr/X/bin:/usr/openwin/bin"

The Solaris Software Companion CD contains unsupported copies of many popular Free Software and Open Source programs from the Internet. They install under /opt/sfw. If you install this software, you may wish to add /opt/sfw/bin to your path as well.

2.1.2. Finding Commands on GNU/Linux and Mac OS X

The situation on GNU/Linux and Mac OS X is considerably simpler. For both systems, a path like the following suffices:

    PATH=/bin:/usr/bin:/usr/X11R6/bin

On Mac OS X the default path is /bin:/sbin:/usr/bin:/usr/sbin. You may wish to add the X11 directory to it:

    PATH=$PATH:/usr/X11R6/bin

Essentially every GNU/Linux program accepts long options (such as --fire-phasers) besides the traditional short ones (-F). In addition, just about every GNU/Linux program accepts the options --help and --version, to print a command-line summary and version information respectively. In the interests of brevity, the individual command descriptions omit the --help and --version options, and they omit the statement that long options apply only to GNU/Linux programs.


Chapter 10. The sed Editor

The sed "stream editor" is one of the most prominent Unix text processing tools. 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

Source code for GNU sed is available from ftp://ftp.gnu.org/gnu/sed/. The Free Software Foundation's home page for sed is http://www.gnu.org/software/sed/sed.html. For more information on sed, see sed & awk, listed in the Bibliography.


10.1. Conceptual Overview

The stream editor, sed, is a noninteractive 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 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.


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.


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

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. 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 nonword 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 (version 4.0 and later).
\oNN | The character whose ASCII octal value is NN (version 4.0 and later).
\xNN | The character whose ASCII hexadecimal value is NN (version 4.0 and later).


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 in the following section, "Alphabetical Summary." Commands marked with a | are specific to GNU sed.

10.4.1. Basic Editing

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

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

10.4.3. Input/Output Processing

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

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

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

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


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 only support up to 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:

/^[    ]*$/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

    /Unix/{

    h

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

    p

    x

    }

Sample input:

    This describes the Unix ls command.

    This describes the Unix cp command.

Sample output:

    ls:

    This describes the Unix ls command.

    cp:

    This describes the Unix 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 the 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 [image] are specific to GNU sed ):

n

Replace n th 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 replace 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 successive substitutions are successful, sed prints multiple copies of the line.

w file

Write the line to file if a replacement was done. In 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 were 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, since non-GNU versions of sed don't implement the command at all, and will therefore fail. If you supply a specific version, then 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 creates the file if it does not exist; if the file exists, its contents are overwritten each time the script is executed. Multiple write commands that direct output to the same file append to the end of the file.

Most Unix versions of sed allow a maximum of only 10 different files to be opened in a script. The GNU version does not have this limit.

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 write 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 awk Programming Language

The awk programming language is often used for text and string manipulation within shell scripts, particularly when input data can be viewed as records and fields. However, it 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 actions

  • 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 Effective awk Programming, listed in the Bibliography.


11.1. Conceptual Overview

awk is a pattern-matching program for processing files, especially when each line has a simple field-oriented layout. The new version of awk, called nawk, provides additional capabilities.[*] Every modern Unix system comes with a version of new awk, and its use is recommended over old awk. The GNU version of awk, called gawk, implements new awk and provides a number of additional features.

[*] It really isn't so new. The additional features were added in 1984, and it was first shipped with System V Release 3.1 in 1987.

Different systems vary in what new and old awk are called. Some have oawk and awk, for the old and new versions, respectively. Others have awk and nawk. Still others only have awk, which is the new version. This example shows what happens if your awk is the old one:

    $ awk 1 /dev/null

    awk: syntax error near line 1

    awk: bailing out near line 1

awk will exit silently if it is the new version.

The POSIX standard for awk is based on new awk, and the standard uses the simple designation awk for that language. Thus, we do also. If your system's awk is the old one, find the new one, and use it for your programs.

Solaris is the only modern Unix system that persists in having old awk as the default version. You should be sure to put /usr/xpg4/bin in your shell's search path before /usr/bin, so that you will get a POSIX-compliant version of awk. Alternatively, just install the GNU version.

Items described here as "common extensions" are often available in different versions of new awk, as well as in gawk, but should not be used if strict portability of your programs is important to you.

The freely available versions of awk described in the section "Source Code," later in this chapter, all implement new awk.

With awk, 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 (with the latest Bell Laboratories version of awk).

In addition, with GNU awk (gawk), you can:

  • Use regular expressions to separate records, as well as fields.

  • Skip to the start of the next file, not just the next record.

  • Perform more powerful string substitutions.

  • Sort arrays.

  • Retrieve and format system time values.

  • Use octal and hexadecimal constants in your program.

  • Do bit manipulation.

  • Internationalize your awk 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 awk programs.


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. POSIX awk 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 the standard input.

11.2.1. Standard Options

The standard options are:

-F fs

Set the field separator to fs. This is the same as setting the built-in variable FS. POSIX awk allows fs to be a regular expression. Each input line, or record, is divided into fields by white space (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

Many examples are shown later in the section "Simple Pattern-Action 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 that are 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 and their types and 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 later section "Internationalization," 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 the "Profiling" section 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.


11.3. Patterns and Procedures

awk scripts consist of patterns and actions :

    pattern  { action }

Both are optional. If pattern is missing, { action } is applied to all lines. If {action} 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 the section "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 section "Operators," 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 ~ (matches) and !~ (doesn't match). See the section "Operators" later in this chapter.

  • The BEGIN pattern lets you specify actions that 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 actions that take place after the last input record is read.

  • BEGIN and END patterns may appear multiple times. The actions are merged as if there had been one large action.

Except for BEGIN and END, patterns can be combined with the Boolean operators || (or), && (and), and ! (not). An inclusive 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-Action 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 lines matching pattern:

    /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 fewer than 20 characters:

    length($0) < 20

  • Print each line that begins with Name: and that contains exactly 7 fields:

    NF == 7 && /^Name:/

  • Print the fields of each record in reverse order, one per line:

    {

            for (i = NF; i >= 1; i--)

                    print $i

    }


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.
 | CONVFMT | String conversion format for numbers ("%.6g"). (POSIX)
 | 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"). (Pre-POSIX awk used this for string conversion also.)
 | 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").


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

While ** and **= are common extensions, they are not part of POSIX awk .


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 using them 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 in operator 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 the section "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
\a | Alert (bell)
\b | Backspace
\f | Form feed
\n | Newline
\r | Carriage return
\t | TAB
\v | Vertical tab
\\ | Literal backslash
\nnn | Octal value nnn
\xnn | Hexadecimal value nn
\" | Literal double quote (in strings)
\/ | Literal slash (in regular expressions)

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


11.7. User-Defined Functions

POSIX awk 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 that 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.

For user-defined functions, no space is allowed between the function name and the left parenthesis when the function is called.


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 since 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, cited in the Bibliography.

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.


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.


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 | asortia | gensuba | 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 b | 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 |  |


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 10 files open simultaneously and one pipe. 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 pipe—even 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

 statementwhile (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 action, 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 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 earlier 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, default 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/actions statements.

nextfile

nextfile {E}

Stop processing the current input file and start new cycle through pattern/actions 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 the section "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 the section "printf Formats," later in the 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 format specifiers.

Example

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 the section "printf Formats," later in the 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, in that it is a mixture of literal text and format specifiers. 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 2 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, default to $0. Return 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 that 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.

Example

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

    BEGIN {

            now = systime(  )

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

            print mesg

    }

    process data ...

    END {

            now = systime(  )

            mesg = strftime("Ended at %Y-%m-%d %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. Output Redirections

For print and printf, dest-expr is an optional expression that directs the output to a file or pipe.

> file

Directs the output to a file, overwriting its previous contents.

>> file

Appends the output to a file, preserving its previous contents. In both of these cases, the file will be created if it does not already exist.

| command

Directs the output as the input to a system command.

|& command

Directs 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.1. 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.precision e[+-]dd).
E | Floating-point format ([-]d.precision E[+-]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. (Unfortunately, not all awk implementations do this correctly.)
' | gawk 3.1.4 and later only. For numeric formats, in locales that support it, supply a thousands-separator character.

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


11.13. Source Code

The following URLs indicate where to get source code for four freely available versions of awk, and for 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

The following chapters describe three popular source code management systems for Unix. 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 related books in the Bibliography.

This chapter covers the following topics:

  • Introduction and terminology

  • Usage models

  • Unix source code management systems

  • Other source code management systems


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 Unix file 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 which 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 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 which 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 then you 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.


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 developers 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 a "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.


12.3. Unix Source Code Management Systems

There are several source code management systems for Unix .

Source Code Control System (SCCS)

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 long-time 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 wide-spread 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.

Revision Control System (RCS)

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.

Concurrent Versions System (CVS)

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 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 systems, and in 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 long-time 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.


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 off-line 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 Revision Control System

The Revision Control System (RCS ) provides a series of commands for maintaining multiple versions of files. It can manage both textual and binary data. While primarily used for software development, RCS can manage other files as well: documentation, textual databases, and so on.

This chapter presents the following topics:

  • Overview of commands

  • Basic operation

  • General RCS specifications

  • Alphabetical summary of commands

The Revision Control System (RCS) is designed to keep track of multiple file revisions, thereby reducing the amount of storage space needed. With RCS you can automatically store and retrieve revisions, merge or compare revisions, keep a complete history (or log) of changes, and identify revisions using symbolic keywords. RCS preserves execute permission on the files it manages, and you can store binary data in RCS files.

RCS is not a standard part of Solaris. It can be obtained from the Free Software Foundation (see http://www.gnu.org/software/rcs/). It typically does come with GNU/Linux and Mac OS X. The Official RCS Homepage may be found at http://www.cs.purdue.edu/homes/trinkle/RCS/. This chapter describes RCS Version 5.7.

For more information, see Applying RCS and SCCS, listed in the Bibliography.


13.1. Overview of Commands

The three most important RCS commands are:

ci | Check in revisions (put a file under RCS control).
co | Check out revisions.
rcs | Set up or change attributes of RCS files.

Two commands provide information about RCS files:

ident | Extract keyword values from an RCS file.
rlog | Display a summary (log) about the revisions in an RCS file.

You can compare RCS files with these commands:

merge | Incorporate changes from two files into a third file.
rcsdiff | Report differences between revisions.
rcsmerge | Incorporate changes from two RCS files into a third RCS file.

The following commands help with configuration management. However, they are considered optional, so they are not always installed:

rcsclean | Remove working files that have not been changed.
rcsfreeze | Label the files that make up a configuration.


13.2. Basic Operation

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

    mkdir RCS

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

    ci file

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

To edit a new revision, check out a copy:

    co -l file

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

    ci file

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

    co file

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

    ci -u file

This checks in the file but immediately checks out a read-only ("unlocked") copy. In practice, you would probably make a "checkpoint" of your working version and then keep going, like this:

    ci -l file

This checks in the file, and then checks it back out again, locked, for continued work. To compare changes between a working file and its latest revision, you can type:

    rcsdiff file

Another useful command is rlog, which shows a summary of log messages. System administrators can use the rcs command to set up the default behavior of RCS .


13.3. General RCS Specifications

This section discusses:

  • Keyword substitution

  • Keywords

  • Example values

  • Revision numbering

  • Specifying the date

  • Specifying states

  • Standard options and environment variables

13.3.1. Keyword Substitution

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

  1. In your working file, type any of the keywords listed below.

  2. Check the file in.

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

    $ keyword $

    with:

    $ keyword : value  $ .

  4. Subsequent check-in and check-out of a file updates any existing keyword values. Unless otherwise noted below, existing values are replaced by new values.

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

13.3.2. Keywords

$Author$ | Username of person who checked in the revision.
$Date$ | Date and time of check-in.
$Header$ | A title that includes the RCS file's full pathname, revision number, date, author, state, and (if locked) the person who locked the file.
$Id$ | Same as $Header$, but exclude the full pathname of the RCS file.
$Locker$ | Username of person who locked the revision. If the file isn't locked, this value is empty.
$Log$ | The message that was typed during check-in to describe the file, preceded by the RCS filename, revision number, author, and date. Log messages accumulate rather than being overwritten.
 | RCS uses the "comment leader" of the $Log$ line for the log messages left in the file. The comment leader stored in the RCS file is useful only for exchanging files with older versions of RCS.
$Name$ | The symbolic name used to check in the revision, if any.
$RCSfile$ | The RCS filename, without its pathname.
$Revision$ | The assigned revision number.
$Source$ | The RCS filename, including its pathname.
$State$ | The state assigned by the -s option of ci or rcs.

13.3.3. Example Values

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

    $Author: arnold $

    $Date: 2004/08/05 10:32:27 $

    $Header: /projects/new/RCS/mydata,v 1.2 2004/08/05 10:32:27 arnold Exp arnold $

    $ID$

    $Locker: arnold $

    $Log: mydata,v

    Revision 1.2  2004/08/05 10:32:27  arnold

    Added more important information.

    Revision 1.1  2004/08/05 10:31:44  arnold

    Initial revision

    $Name:  $

    $RCSfile: mydata,v $

    $Revision: 1.2 $

    $Source: /projects/new/RCS/mydata,v $

    $State: Exp $

    Test data file.

    This second line is very important.

13.3.4. Revision Numbering

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

    co -l -r1.4 ch01

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

    ci -r2 ch01

This creates revision 2.1. (Revision numbers always start at one, not at zero.) You can also create a branch from an earlier revision. The following command creates revision 1.4.1.1:

    ci -r1.4.1 ch01

Numbers that begin with a period are considered to be relative to the default branch of the RCS file. Normally, this is the "trunk" of the revision tree.

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

    ci -u -nPrototype *.c

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

    rcsdiff -r$ ch01

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

    rcs -nDraft:$ ch*

assigns a name to the revision numbers associated with several chapter files. (These last two examples require that the file contain a $ID$ line.)

13.3.5. Specifying the Date

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

    2000/01/10 02:00:00     Year/month/day  time

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

    6:00 pm lt              Assuming today is Jan. 10, 2000

    2:00 AM, Jan. 10, 2000

    Mon Jan 10 18:00:00 2000 LT

    Mon Jan 10 18:00:00 PST 2000

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

13.3.6. Specifying States

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

13.3.7. Standard Options and Environment Variables

RCS defines an environment variable, RCSINIT, which sets up default options for RCS commands. If you set RCSINIT to a space-separated list of options, they will be prepended to the command-line options that you supply to any RCS command.

Six options are useful to include in RCSINIT: -q, -V, -V n, -T, -x, and -z. They can be thought of as standard options because most RCS commands accept them.

-q[R]

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

-T

If the file with the new revision has a later modification time than that of the RCS file, update the RCS file's modification time. Otherwise, preserve the RCS file's modification time. This option should be used with care; see the discussion in the ci manpage for more detail.

-V

Print the RCS version number.

-V n

Emulate version n of RCS; useful when trading files between systems that run different versions. n can be 3, 4, or 5.

-x suffixes

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

-z timezone

timezone controls the output format for dates in keyword substitution. timezone should have one of the following values:

Value | Effect
empty | Default format: UTC with no time zone and slashes separating the parts of the date.
LT | The local time and date, in ISO-8601 format, with time-zone indication (YYYY-MM-DD HH:MM:SS-ZZ).
±hh:mm | With a numeric offset from UTC, the output is in ISO-8601 format.

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

    ci -x,v/ ch01    Second suffix is blank

searches in order for the RCS filenames:

    RCS/ch01,v

    ch01,v

    RCS/ch01

RCS allows you to specify a location for temporary files. It checks the environment variables TMPDIR, TMP, and TEMP, in that order. If none of those exist, it uses a default location, such as /tmp.


13.4. Alphabetical Summary of Commands

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

ci

ci [options] files

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

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

Options

-d[date]

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

-f[R]

Force a check-in even if there are no differences.

-i[R]

Initial check-in, report an error if the RCS file already exists.

-I[R]

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

-j[R]

Just check in and do not initialize. Report an error if the RCS file does not already exist.

-k[R]

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

-l[R]

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

-m msg

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

-M[R]

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

-n name

Associate a text name with the new revision number.

-N name

Same as -n, but override a previous name.

-r R

Check the file in as revision R.

-r

Without a revision number, -r restores the default behavior of releasing a lock and removing the working file. It is intended to override any default -l or -u set up by aliases or scripts. The behavior of -r in ci is different from most other RCS commands.

-s state

Set the state of the checked-in revision.

-t file

Replace RCS file description with contents of file. This works only for initial check-in.

-t-string

Replace RCS file description with string. This works only for initial check-in.

-u[R]

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

-w user

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

Examples

Check in chapter files using the same log message:

    ci -m'First round edits' chap*

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

    ci -u prog.c

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

    ci -r2 -nPrototype prog.c

co

co [options] files

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

Options

-d date

Retrieve latest revision whose check-in timestamp is on or before date.

-f[R]

Force the working file to be overwritten.

-I[R]

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

-j R2: R3[, ...]

This works like rcsmerge. R2 and R3 specify two revisions whose changes are merged into a third file: either the corresponding working file or a third revision (any R specified by other co options). Multiple comma-separated pairs may be provided; the output of the first join becomes the input of the next. See the co manpage for more details.

-k c

Expand keyword symbols according to flag c. c can be:

b | Like -ko, but uses binary I/O. This is most useful on non-Unix systems.
kv | Expand symbols to keyword and value (the default). Insert the locker's name only during a ci -l or co -l.
kvl | Like kv, but always insert the locker's name.
k | Expand symbols to keywords only (no values). This is useful for ignoring trivial differences during file comparison.
o | Expand symbols to keyword and value present in previous revision. This is useful for binary files that don't allow substring changes.
v | Expand symbols to values only (no keywords). This prevents further keyword substitution and is not recommended.

-l[R]

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

-M[R]

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

-p[R]

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

-r[R]

Retrieve the latest revision or, if R is given, retrieve the latest revision that is equal to or lower than R. If R is $, retrieve the version specified by the keywords in the working file.

-s state

Retrieve the latest revision having the given state.

-u[R]

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

-w[user]

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

Examples

Sort the latest stored version of file :

    co -p file | sort

Check out (and lock) all files whose names start with an uppercase letter for editing:

    co -l [A-Z]*

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

    co -r3 *,v                   Latest revisions of release 3

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

    co -rPrototype *,v           Latest revisions named Prototype

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

                                 modified on or before the date

ident

ident [options] [files]

Extract keyword/value symbols from files. files can be text files, object files, or dumps. ident accepts the standard option -V.

Options

-q

Suppress warning message when no keyword patterns are found.

-V

Print the version number of ident.

Examples

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

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

the following output is produced:

    $ ident prog.c prog.o

    prog.c:

         $Author: arnold $

    prog.o:

         $Author: arnold $

Show keywords for all RCS files (suppress warnings):

    co -p RCS/*,v | ident -q

merge

merge [options] [diff3 options] file1 file2 file3

Perform a three-way merge of files (via diff3) and place changes in file1. file2 is the original file. file1 is the "good" modification of file2. file3 is another, conflicting modification of file2. merge finds the differences between file2 and file3, and then incorporates those changes into file1. If both file1 and file3 have changes to common lines, merge warns about overlapping lines and inserts both choices in file1. The insertion appears as follows:

    <<<<<<< file1

    lines from file1

    ========

    lines from file3

    >>>>>>> file3

You'll need to edit file1 by deleting one of the choices. merge exits with a status of 0 (no overlaps), 1 (some overlaps), or 2 (unknown problem). See also rcsmerge.

merge accepts the -A, -e, and -E options for diff3, and simply passes them on, causing diff3 to perform the corresponding kind of merge. See the entry for diff3 in Chapter 2 for details. (The -A option is for the GNU version of diff3.)

Options

-L label

This option may be provided up to three times, supplying different labels in place of the filenames file1, file2, and file3, respectively.

-p

Send merged version to standard output instead of to file1.

-q

Produce overlap insertions but don't warn about them.

rcs

rcs [options] files

An administrative command for setting up or changing the default attributes of RCS files. rcs requires you to supply at least one option. (This is for "future expansion.")

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

Options

-a users

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

-A otherfile

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

-b[R]

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

-c' s'

The comment leader for $Log$ keyword is set to string s. You could, for example, set s to .\" for troff files or set s to * for C programs. (You would need to manually insert an enclosing /* and */ before and after $Log$.)

-c is obsolescent; RCS uses the character(s) preceding $Log$ in the file as the comment leader for log messages. You may wish to set this, though, if you are accessing the RCS file with older versions of RCS.

-e[users]

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

-i

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

-I

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

-k c

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

-l[R]

Lock revision R or the latest revision. -l "retroactively locks" a file and is useful if you checked out a file incorrectly by typing co instead of co -l. rcs will ask you if it should break the lock if someone else has the file locked.

-L

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

-m R: msg

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

-M

Do not send mail when breaking a lock. This is intended for use by RCS frontends, not for direct use by users!

-n flags

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

name:R

Associate name with revision R.

name:

Associate name with latest revision.

name

Remove association of name.

-N flags

Same as -n, but overwrite existing names.

-o R_list

Delete (outdate) revisions listed in R_list. R_list can be specified as: R1, R1:R2, R1:, or :R2. When a branch is given, -o deletes only the latest revision on it. The - range separator character from RCS versions prior to 5.6 is still valid.

-s state[: R]

Set the state of revision R (or the latest revision) to the word state.

-t[file]

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

-t-string

Replace RCS file description with string.

-u[R]

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

-U

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

Examples

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

    rcs -nTo_customer: RCS/*

Add three users to the access list of file beatle_deals:

    rcs -ageorge,paul,ringo beatle_deals

Delete revisions 1.2 through 1.5:

    rcs -o1.2:1.5 doc

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

    echo "$description" | rcs -t file

rcsclean

rcsclean [options] [files]

Although included with RCS, this command is optional and might not be installed on your system. rcsclean compares checked-out files against the corresponding latest revision or revision R (as given by the options). If no differences are found, the working file is removed. (Use rcsdiff to find differences.) rcsclean is useful in makefiles; for example, you could specify a "clean-up" target to update your directories. rcsclean is also useful prior to running rcsfreeze. rcsclean accepts the standard options -q, -V, -V n, -T, -x, and -z.

Options

-k c

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

-n[R]

Show what would happen but don't actually execute.

-r[R]

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

-u[R]

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

Example

Remove unchanged copies of program and header files:

    rcsclean *.c *.h

rcsdiff

rcsdiff [options] [diff_options] files

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

# of revisions | Comparison made
None | Working file against latest revision.
One | Working file against specified revision.
Two | One revision against the other.

rcsdiff accepts the standard options -q, -V, -V n, -T, -x, and -z, as well as diff_options, which can be any valid diff option. rcsdiff exits with a status of 0 (no differences), 1 (some differences), or 2 (unknown problem). The -c and -u options to diff can be very useful with rcsdiff.

rcsdiff prints "retrieving revision ..." messages to standard error, as well as a line of equals signs for separating multiple files. It is often useful to redirect standard error and standard output to the same file.

Options

-k c

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

-r R1

Use revision R1 in the comparison.

-r R2

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

Examples

Compare the current working file against the last checked-in version:

    rcsdiff -c ch19.sgm 2>&1 | more

Compare the current working file against the very first version:

    rcsdiff -c -r1.1 ch19.sgm 2>&1 | more

Compare two earlier versions of a file against each other:

    rcsdiff -c -r1.3 -r1.4 ch19.sgm 2>&1 | more

rcsfreeze

rcsfreeze [name]

Although included with RCS, this shell script is optional and might not be installed on your system. rcsfreeze assigns a name to an entire set of RCS files, which must already be checked in. This is useful for marking a group of files as a single configuration. The default name is C_n, where n is incremented each time you run rcsfreeze.

rcsmerge

rcsmerge [options] [diff3 options] file

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

rcsmerge accepts the -A, -e, and -E options for diff3 and simply passes them on, causing diff3 to perform the corresponding kind of merge. See merge, and also see the entry for diff3 in Chapter 2 for details. (The -A option is for the GNU version of diff3.)

Options

-k c

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

-p[R]

Send merged version to standard output instead of overwriting file.

-r[R]

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

Examples

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

    $ co -l prog.c      Get latest revision

         (Edit latest revision by adding updates for revision 1.3, then:)

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

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

    rcsmerge -r3.5 -r3.2 chap08

rlog

rlog [options] files

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

Options

-b

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

-d dates

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

d1 < d2

Select revisions between date d1 and d2, inclusive.

d1 <

Select revisions made on or after date1.

d1 >

Select revisions made on or before date1.

Timestamp comparisons are strict. If two files have exactly the same time, < and > won't work. Use <= and >= instead.

-h

Display the beginning of the normal rlog listing.

-l[users]

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

-L

Skip files that aren't locked.

-N

Don't print symbolic names.

-r[list]

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

R1

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

R1.

If R1 is a branch, select its latest revision.

R1:R2

Select revisions R1 through R2.

:R1

Select revisions from beginning of branch through R1.

R1:

Select revisions from R1 through end of branch.

The - range separator character from RCS versions prior to 5.6 is still valid.

-R

Display only the name of the RCS file.

-s states

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

-t

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

-w[users]

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

Examples

Display the revision histories of all your RCS files:

    rlog RCS/*,v | more

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

    rlog -R -L -larnold RCS/*

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

    rlog -t calc.c


Chapter 14. The Concurrent Versions System

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 as 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 Essential CVS, which is cited in the Bibliography. See that book for much more information on CVS. The Internet starting point for CVS is http://www.cvshome.org/.


14.1. Conceptual Overview

The basic concepts for source code management systems were presented earlier 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 14-1 is a quick-start guide to using CVS. You would use the commands in the order shown to create and start using a CVS repository. (The basic steps for the Subversion source code management system are shown in more detail in the section "Using Subversion: A Quick Tour" in Chapter 15. Using CVS is similar.)

Table 14-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.

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

14.1.2. 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 for more details.


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

14.2.1. 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 that the server allows connections to. 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 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 the later section "CVSROOT Variables."

-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 only sets 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.

14.2.2. 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 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 to be 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 the later section "Keywords and Keyword Modes."

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


14.3. 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 the user is 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 terribly, terribly insecure. You should avoid it completely; use ssh instead.


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

14.4.1. 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 terribly, terribly 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 the earlier section "CVS Wrappers."

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.

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


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

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.

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.


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

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

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

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

14.6.2. Legal Date Keywords

CVS also allows short English phrases such as "last Wednesday" and "a month ago" to be used in placed 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)

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

Some of the time-zone abbreviations CVS recognizes are ambiguous. CVS recognizes only one meaning for each of the ambiguous time zones. However, which meaning is recognized may vary depending on your operating system, and on how CVS was configured when it was compiled.

Table 14-2 shows the valid civilian time-zone abbreviations for CVS. Table 14-3 shows military time-zone abbreviations that CVS recognizes.

Table 14-2. Civilian time-zone abbreviations

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 14-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


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

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

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

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


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

Example

    $ 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 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

-a usernames

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.

-A filename

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; or, 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.

-c string

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 isn't 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 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.

-m revision: message

Replace the log message of the designated revision of a file with the specified message.

-n tagname[:[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.

-N tagname[:[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.

-o range

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

-s state[: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 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.

-V N

Write an RCS file compatible with RCS version N. This option isn't used in CVS anymore, and it is not available in CVS 1.9.20 and later.

-x suffix

Specify the suffix for the RCS file. This option is not used or available in CVS (all CVS files use ,v as the suffix).

Example

    $ cvs admin -kb AcceptanceTest.doc

    RCS file: /var/lib/cvs/wizzard/doc/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 supplied, the files in the current sandbox are shown. See also rannotate.

Synonym: ann.

Standard subcommand options: -D, -f, -l, -r, -R.

Option

-F

Show annotations for binary files.

Example

    $ cvs annotate Makefile

    Annotations for Makefile

    ***************

    1.2  (arnold     01-Sep-02): #

    1.2  (arnold     01-Sep-02): # Wizzard project Makefile

    1.2  (arnold     01-Sep-02): # 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.

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

Example

    $ 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 invokes 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.

Example

    /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.rtf,v

    done

    Checking in doc/Design.rtf;

    /var/lib/cvs/wizzard/doc/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. This includes full support for the line and group format options; see the entry for diff in Chapter 2.

Example

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.

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

Option

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

Example

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

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.

Example

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

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 that is 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 search 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 tagged with CVS rtag.

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

Example

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

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

Example

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

Example

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

Example

    $ 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

    date: 2002/08/31 13:37:56;  author: arnold;  state: Exp;

    Creating a structure.

    ...

login

cvs [cvs-options] login

Log in to a CVS pserver session. This command is needed only with the pserver connection mode. See also logout.

Synonyms: none.

Example

    $ acct=:pserver:arnold:password:@cvs.nosuch.net:/var/lib/cvs

    $ cvs -d $acct 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.

Example

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

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

Option

-F

Show annotations for binary files.

Example

    $ cvs rannotate wizzard/Makefile

    Annotations for wizzard/Makefile

    ***************

    1.2  (arnold     01-Sep-02): #

    1.2  (arnold     01-Sep-02): # Wizzard project Makefile

    1.2  (arnold     01-Sep-02): # 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 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.

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.

Example

    $ 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,18 ****

      # Makefile for the Wizzard project

      # First created by A Robbins, 1 September 2002

      #

    ! # Current revision $Revision: 1.1 $

      # On branch $Name:  $ (not expanded if this is the trunk)

    ! # Latest change by

      # $Author: ellie $ on $Date: 2005/11/28 20:16:25 $

      #

      ##

      # Initial declarations

      #

      CC=gcc

    ! SUBDIRS = man doc src lib

      # Declaring phony targets

    --- 2,18 ----

      # Makefile for the Wizzard project

      # First created by A Robbins, 1 September 2002

      #

    ! # Current revision $Revision: 1.1 $

      # On branch $Name:  $ (not expanded if this is the trunk)

    ! # Latest change by

      # $Author: ellie $ on $Date: 2005/11/28 20:16:25 $

      #

      ##

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

Example

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

Option

-f

Delete the files from the sandbox before removing them from the repository.

Example

    $ 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 option: -l.

Options

-b

Provide information only about the revisions or a file on the default branch, normally the highest branch on the trunk.

-d dates

Provide information only on 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 only on 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 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.

Example

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

Option

-v

Include information about tags.

Example

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

Example

    $ 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 the 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 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 the 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.

Example

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

Example

    $ 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 explains uses of the cvs watch family of commands. See also edit, editors, unedit, and watchers.

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.

Option

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

Examples

    $ cvs watch on Makefile         Enable watching

    $ cvs watch add Makefile        Add me to list of watchers

watchers

cvs [cvs-options] watchers [-lR] [files ...]

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

Example

    $ cvs watchers Makefile

    Makefile doppel edit unedit commit

    arnold edit unedit commit


Chapter 15. 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

Most of the material in this chapter is adapted from Version Control with Subversion, which is cited in the Bibliography. See that book for much more information on Subversion.


15.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!

15.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 and unlike RCS, 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 to 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 for when you need to produce a bug fix for an older version of the project, or attempt to retrofit a fix or feature from current development into an older version.

15.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 renames—which might happen to files, but which are really changes to the contents of some containing directory—aren'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 old—perhaps completely unrelated—file. With Subversion, you can add, delete, copy, and rename both files and directories. 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 properties—keys and their values—associated 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 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 server—authentication, 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 commands similar to those of CVS, making it straightforward to transfer your CVS habits to Subversion.

15.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 quickest 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.

15.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 the "svn Subcommands" section later in the 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 only does keyword expansion 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 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: joe $. 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: ch15.xml,v 1.1 2005/11/28 20:16:26 ellie Exp ellie $

This keyword is a compressed combination of the other keywords. Its substitution looks like $Id: ch15.xml,v 1.1 2005/11/28 20:16:26 ellie Exp ellie $, and is interpreted to mean that the file calc.c was last changed in revision 148 on the evening of July 28, 2002 by the user sue.


15.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 pre-built binary for your system, or use a package manager to download and install it.

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

15.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 back-end

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 web site; 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 back-end

  • 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; this is provided by DeltaV, described in RFC 3253. See http://www.webdav.org for more information.

  • Pluggable client-side diff programs

  • Progressive multilingual support

15.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 that 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. Building Subversion follows the general steps outlined in the section "Building Software," in Chapter 1.


15.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 of 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!";


15.4. The Subversion Command Line Client: svn

The syntax for the Subversion command line client, svn, is:

    svn [options

] subcommand [arguments]

The options and subcommand may be provided in any order.

15.4.1. svn Options

While Subversion has different options for its subcommands, all options are global—that is, each option is guaranteed to mean the same thing regardless of the subcommand that you use it with. For example, --verbose (-v) always means "verbose output," no matter which 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. Normally, 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 changes—either in the sandbox 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 "I know what I'm doing as well as the possible repercussions of doing it, 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 that 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 other—unversioned--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 since 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 subcommands—usually those that have the potential to remove or undo your local modifications—do 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 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 list of revision keywords is provided later in this section.

--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 copy—that 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 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

Print output in XML format.

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}. Full details are provided in Version Control with Subversion.

15.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 | --non-recursive (-N)
--config-dir dir | --quiet (-q)
--no-auto-props | --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 in-line 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 | --password pass
--no-auth-cache | --revision rev, -r rev
--non-interactive | --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 | --password pass
--no-auth-cache | --revision rev, -r rev
--non-interactive | --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.

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 | --password pass
--no-auth-cache | --quiet (-q)
--non-interactive | --revision rev, -r rev
--non-recursive (-N) | --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 like 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 rarely need these options.

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 don't 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.

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. Subversion prompts you to either abort the commit, continue with no message, or edit the message again.

Alternate Names: | ci (short for "check in," not co, which is short for "check out")
Changes: | Working copy, repository
Accesses Repository: | Yes

Options

--config-dir dir | --non-interactive
--encoding enc | --non-recursive (-N)
--file file, -F file | --password pass
--force-log | --quiet (-q)
--message text, -m text | --targets filename
--no-auth-cache | --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.

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 | --no-auth-cache
--editor-cmd editor | --non-interactive
--encoding enc | --password pass
--file file, -F file | --quiet (-q)
--force-log | --revision rev, -r rev
--message text, -m text | --username user

Examples

Copy an item within your working copy (just schedule 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 schedule the copy—nothing goes into the repository until you commit):

    $ svn copy file:///tmp/repos/test/far-away near-here

    A         near-here

This is the recommended way to resurrect a dead file in your repository!

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.

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 | --no-auth-cache
--editor-cmd editor | --non-interactive
--encoding enc | --password pass
--file file, -F file | --quiet (-q)
--force-log | --targets filename
--force | --username user
--message text, -m text |

diff

svn

 diff [-r N[:M]] [--old old-tgt][--new new-tgt] [path ...]

svn diff -r N:M URLsvn 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 | --non-recursive (-N)
--diff-cmd cmd | --notice-ancestry
--extensions args, -x args | --old old-target
--new new-target | --password pass
--no-auth-cache | --revision rev, -r rev
--no-diff-deleted | --username user
--non-interactive |

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 from the repository specified by URL (at revision rev if it is given, otherwise at HEAD) into path. 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 | --password pass
--force | --quiet (-q)
--no-auth-cache | --revision rev, -r rev
--non-interactive | --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 | --no-auth-cache
--config-dir dir | --no-auto-props
--editor-cmd editor | --non-interactive
--encoding enc | --non-recursive (-N)
--file file, -F file | --password pass
--force-log | --quiet (-q)
--message text, -m text | --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 | --recursive (-R)
--no-auth-cache | --revision rev, -r rev
--non-interactive | --username user
--password pass | --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 sue         28361 Jan 16 23:18 README.txt

         27 sue             0 Jan 18 15:27 INSTALL

         24 joe               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, svn log 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 | --revision rev, -r rev
--incremental | --stop-on-copy
--no-auth-cache | --targets filename
--non-interactive | --username user
--password pass | --verbose (-v)
--quiet (-q) | --xml

Examples

To see the log messages for all the paths that changed in your working copy, run svn log from the top (some long output lines have wrapped):

    $ svn log

    -------------------------------------------------------------------

    r20 | joe | 2003-01-17 22:56:19 -0600 (Fri, 17 Jan 2003) | 1 line

    Tweak.

    -------------------------------------------------------------------

    r17 | sue | 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 | sue | 2003-01-13 00:43:13 -0600 (Mon, 13 Jan 2003) | 1 line

    Added defines.

    -------------------------------------------------------------------

    r28 | sue | 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

    -------------------------------------------------

then 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 | sue | 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 | --non-interactive
--diff3-cmd cmd | --non-recursive (-N)
--dry-run | --password pass
--force | --quiet (-q)
--ignore-ancestry | --revision rev, -r rev
--no-auth-cache | --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 | --no-auth-cache
--editor-cmd editor | --non-interactive
--encoding enc | --password pass
--file file, -F file | --quiet (-q)
--force-log | --username user
--message text, -m text |

move

svn move src dst

This command moves (renames) a file or directory in your working copy or in the repository.

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.

Subversion does not support moving between working copies and URLs. In addition, you can only move files 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 | --no-auth-cache
--editor-cmd editor | --non-interactive
--encoding enc | --password pass
--file file, -F file | --quiet (-q)
--force-log | --revision rev, -r rev
--force | --username user
--message text, -m text |

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, whereas 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 | --recursive (-R)
--no-auth-cache | --revision rev, -r rev
--non-interactive | --revprop
--password pass | --username user
--quiet (-q) |

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 | --password pass
--editor-cmd editor | --revision rev, -r rev
--encoding enc | --revprop
--no-auth-cache | --username user
--non-interactive |

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 | --recursive (-R)
--no-auth-cache | --revprop
--non-interactive | --strict
--password pass | --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 | --recursive (-R)
--no-auth-cache | --revision rev, -r rev
--non-interactive | --revprop
--password pass | --username user
--quiet (-q) | --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 : sue

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 | --quiet (-q)
--encoding enc | --recursive (-R)
--file file, -F file | --revision rev, -r rev
--force | --revprop
--no-auth-cache | --targets filename
--non-interactive | --username user
--password pass |

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 execute permission:

    $ 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 | --recursive (-R)
--quiet (-q) | --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.

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 not only reverts 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 | --recursive (-R)
--quiet (-q) | --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, print 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 dir | --password pass
--no-auth-cache | --quiet (-q)
--no-ignore | --show-updates (-u)
--non-interactive | --username user
--non-recursive (-N) | --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

--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 sue        wc/bar.c

           *     965       922 joe        wc/foo.c

    A  +         965       687 joe        wc/qax.c

                 965       687 joe        wc/zig.c

    Head revision:   981

switch

svn switch URL [path]

This subcommand updates your working copy to mirror a new URL—usually 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 | --password pass
--diff3-cmd cmd | --quiet (-q)
--no-auth-cache | --relocate
--non-interactive | --revision rev, -r rev
--non-recursive (-N) | --username user

Examples

If you're currently inside the directory vendors, which was branched to fixed, and you'd like to switch your working copy to that branch:

    $ svn switch http://svn.red-bean.com/repos/branches/fixed .

    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.

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 check 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 that 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
C | Conflict
D | Deleted
G | Merged
U | Updated

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.

Alternate Names: | up
Changes: | Working copy
Accesses Repository: | Yes

If you want to examine an older revision of a single file, you may want to use svn cat.

Options

--config-dir dir | --password pass
--diff3-cmd cmd | --quiet (-q)
--no-auth-cache | --revision rev, -r rev
--non-interactive | --username user
--non-recursive (-N) |


15.5. Repository Administration: svnadmin

svnadmin is the administrative tool for monitoring and repairing your Subversion repository.

15.5.1. svnadmin Options

--bdb-log-keep

Disable automatic log removal of database log files. (Berkeley DB-specific)

--bdb-txn-nosync

Disable use of fsync( ) when committing database transactions. (Berkeley DB-specific)

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

15.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 exists in 1.0.x only 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 this "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.

Options

--clean-logs
list-dblogs

svnadmin list-dblogs repos_path

List Berkeley DB log files. Berkeley DB creates logs of all changes to the repository, allowing the repository to recover in the face of catastrophe. Unless you enable DB_LOGS_AUTOREMOVE, the log files accumulate, although most are no longer used and can be deleted to reclaim disk space.

list-unused-dblogs

svnadmin list-unused-dblogs repos_path

List unused Berkeley DB log files (see svnadmin list-dblogs).

Example

Remove all unused log files 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 | --parent-dir
--ignore-uuid | --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 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.


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

15.6.1. svnlook Options

Options in svnlook are global, just like in svn and svnadmin; however, most options only apply to one subcommand since 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 too for the property-related commands.

--version

Display version and copyright information.

15.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, then 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 showing 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.


15.7. Providing Remote Access: svnserve

svnserve provides access to Subversion repositories using the svn network protocol. You can run svnserve either as a standalone server process, or you can have another process, such 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.

15.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 is 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 pathnames 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.


15.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, which is cited in the Bibliography. 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 a revision can be created when the original revision contained paths that were filtered out. This option removes such empty revisions from the dump.

--preserve-revprops

If empty revisions are being kept, preserve their revision properties (such as log message, author, date, and so on). 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, subsequent revisions are renumbered, so that all revision numbers are contiguous.

Example

Dump the repository, 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, non-switched 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.


Chapter 16. The GNU make Utility

The make program is a long time mainstay of the Unix toolset. It automates the building of software and documentation based on a specification of dependencies among files; e.g., object files that depend upon program source files, or PDF files that depend upon documentation program input files. GNU make is the standard version for GNU/Linux and Mac OS X.

This chapter presents the following topics:

  • Conceptual overview

  • Command-line syntax

  • Makefile lines

  • Macros

  • Special target names

  • Writing command lines

For more information, see Managing Projects with GNU make and GNU Make: A Program for Directing Recompilation, both listed in the Bibliography.

The software download site for GNU make is ftp://ftp.gnu.org/gnu/make/.


16.1. Conceptual Overview

The make program generates a sequence of commands for execution by the Unix shell. It uses a table of file dependencies provided by the programmer, and with this information, can perform updating tasks automatically for the user. It can keep track of the sequence of commands that create certain files, and the list of files or programs that require other files to be current before they can be rebuilt correctly. When a program is changed, make can create the proper files with a minimum of effort.

Each statement of a dependency is called a rule. Rules define one or more targets, which are the files to be generated, and the files they depend upon, the prerequisites or dependencies. For example, prog.o would be a target that depends upon prog.c; each time you update prog.c, prog.o must be regenerated. It is this task that make automates, and it is a critical one for large programs that have many pieces.

The file containing all the rules is termed a makefile; for GNU make, it may be named GNUmakefile, makefile or Makefile, in which case make will read it automatically, or you may use a file with a different name and tell make about it with the -f option.

Over the years, different enhancements to make have been made by many vendors, often in incompatible ways. POSIX standardizes how make is supposed to work. Today, GNU make is the most popular version in the Unix world. It has (or can emulate) the features of just about every other version of make, and many Open Source programs require it.

This chapter covers GNU make. Commercial Unix systems come with versions derived from the original System V version; these can be used for bootstrapping GNU make if need be. On the x86 versions of Solaris 10, you can find GNU make in /usr/sfw/bin/gmake. It isn't available on the Sparc version, although it can be easily bootstrapped with the standard version of make in /usr/ccs/bin.


16.2. Command-Line Syntax

The make program is invoked as follows:

    make  [options

]  [targets]  [macro definitions]

Options, targets, and macro definitions can appear in any order. The last assignment to a variable is the one that's used. Macro definitions are typed as:

    name=string

or

    name:=string

For more information, see the section "Creating and Using Macros," later in this chapter.

If no GNUmakefile, makefile, or Makefile exists, make attempts to extract the most recent version of one from either an RCS file, if one exists, or from an SCCS file, if one exists. Note though, that if a real makefile exists, make will not attempt to extract one from RCS or SCCS, even if the RCS or SCCS file is newer than the makefile.

16.2.1. Options

Like just about every other GNU program, GNU make has both long and short options. The available options are as follows:

-b

Silently accepted, but ignored, for compatibility with other versions of make.

-B, --always-make

Treat all targets as out of date. All targets are remade, no matter what the actual status is of their prerequisites.

-C dir, --directory=dir

Change directory to dir before reading makefiles. With multiple options, each one is relative to the previous. This is usually used for recursive invocations of make.

-d

Print debugging information in addition to regular output. This information includes which files are out of date, the file times being compared, the rules being used to update the targets, and so on. Equivalent to --debug=a.

--debug[= debug-opt]

Print debugging information as specified by debug-opt, which is one or more of the following letters, separated by spaces or commas. With no argument, provide basic debugging.

a

All. Enable all debugging.

b

Basic. Print each target that is out of date, and whether or not the build was successful.

i

Implicit. Like basic, but include information about the implicit rules searched for each target.

j

Jobs. Provide information about subcommand invocation.

m

Makefiles. Enable basic debugging, and any of the other options, for description of attempts to rebuild makefiles. (Normally, make doesn't print information about its attempts to rebuild makefiles.)

v

Verbose. Like basic, but also print information about which makefiles were read, and which prerequisites did not need to be rebuilt.

-e, --environment-overrides

Environment variables override any macros defined in makefiles.

-f file, --file=file, --makefile=file

Use file as the makefile; a filename of - denotes standard input. -f can be used more than once to concatenate multiple makefiles. With no -f option, make first looks for a file named GNUmakefile, then one named makefile, and finally one named Makefile.

-h, --help

Print a usage summary, and then exit.

-i, --ignore-errors

Ignore error codes from commands (same as .IGNORE).

-I dir, --include-dir=dir

Look in dir for makefiles included with the include directive. Multiple options add more directories to the list; make searches them in order.

-j [count], --jobs[= count]

Run commands in parallel. With no count, make runs as many separate commands as possible. (In other words, it will build all the targets that are independent of each other, in parallel.) Otherwise, it runs no more than count jobs. This can decrease the time it takes to rebuild a large project.

-k, --keep-going

Abandon the current target when it fails, but keep working with unrelated targets. In other words, rebuild as much as possible.

-l [load], --load-average[= load], --max-load[= load]

If there are jobs running and the system load average is at least load, don't start any new jobs running. Without an argument, clear a previous limit. The load value is a floating point number.

-m

Silently accepted, but ignored, for compatibility with other versions of make.

-n, --dry-run, --just-print, --recon

Print commands but don't execute (used for testing). -n prints commands even if they begin with @ in the makefile.

Lines that contain $(MAKE) are an exception. Such lines are executed. However, since the -n is passed to the subsequent make in the MAKEFLAGS environment variable, that make also just prints the commands it executes. This allows you to test out all the makefiles in a whole software hierarchy without actually doing anything.

--no-print-directory

Don't print the working directory as make runs recursive invocations. Useful if -w is automatically in effect but you don't want to see the extra messages.

-o file, --assume-old= file, --old-file= file

Pretend that file is older than the files that depend upon it, even if it's not. This avoids remaking the other files that depend on file. Use this in cases where you know that the changed contents of file will have no effect upon the files that depend upon it; e.g., changing a comment in a header file.

-p, --print-data-base

Print macro definitions, suffixes, and built-in rules. In a directory without a makefile, use env -i make -p to print out the default variable definitions and built-in rules.

-q, --question

Query; return 0 if the target is up to date; nonzero otherwise.

-r, --no-builtin-rules

Do not use the default rules. This also clears out the default list of suffixes and suffix rules.

-s, --quiet, --silent

Do not display command lines (same as .SILENT).

-S, --no-keep-going, --stop

Cancel the effect of a previous -k. This is only needed for recursive make invocations, where the -k option might be inherited via the MAKEFLAGS environment variable.

-t, --touch

Touch the target files, causing them to be updated.

-v, --version

Print version, copyright, and author information, and exit.

-w, --print-directory

Print the working directory, before and after executing the makefile. Useful for recursive make invocations. This is usually done by default, so it's rare to explicitly need this option.

--warn-undefined-variables

Print a warning message whenever an undefined variable is used. This is useful for debugging complicated makefiles .

-W file, --assume-new= file, --new-file= file, --what-if= file

Treat file as if it had just been modified. Together with -n, this lets you see what make would do if file were modified, without actually doing anything. Without -n, make pretends that the file is freshly updated, and acts accordingly.


16.3. Makefile Lines

Instructions in the makefile are interpreted as single lines. If an instruction must span more than one input line, use a backslash (\) at the end of the line so that the next line is considered a continuation. The makefile may contain any of the following types of lines:

Blank lines

Blank lines are ignored.

Comment lines

A number sign (#) can be used at the beginning of a line or anywhere in the middle. make ignores everything after the #.

Dependency lines

One or more target names, a single- or double-colon separator, and zero or more prerequisites:

    targets : prerequisites

    targets :: prerequisites

In the first form, subsequent commands are executed if the prerequisites are newer than the target. The second form is a variant that lets you specify the same targets on more than one dependency line. (This second form is useful when the way you rebuild the target depends upon which prerequisite is newer.) In both forms, if no prerequisites are supplied, subsequent commands are always executed (whenever any of the targets are specified). For example, the following is invalid, since single-colon rules do not allow targets to repeated:

    # PROBLEM: Single colon rules disallow repeating targets

    whizprog.o: foo.h

            $(CC) -c $(CFLAGS) whizprog.o

            @echo built for foo.h

    whizprog.o: bar.h

            $(CC) -c $(CFLAGS) whizprog.o

            @echo built for bar.h

In such a case, the last set of rules is used and make issues a diagnostic. However, double-colon rules treat the dependencies separately, running each set of rules if the target is out of date with respect to the individual dependencies:

    # OK: Double colon rules work independently of each other

    whizprog.o:: foo.h

            $(CC) -c $(CFLAGS) whizprog.o

            @echo built for foo.h

    whizprog.o:: bar.h

            $(CC) -c $(CFLAGS) whizprog.o

            @echo built for bar.h

No tab should precede any targets. (At the end of a dependency line, you can specify a command, preceded by a semicolon; however, commands are typically entered on their own lines, preceded by a tab.)

Targets of the form library(member) represent members of archive libraries, e.g., libguide.a(dontpanic.o). Furthermore, both targets and prerequisites may contain shell-style wildcards (e.g., *.c). make expands the wildcard and uses the resulting list for the targets or prerequisites.

Suffix rules

These specify that files ending with the first suffix can be prerequisites for files ending with the second suffix (assuming the root filenames are the same). Either of these formats can be used:

    .suffix.suffix:

    .suffix:

The second form means that the root filename depends on the filename with the corresponding suffix.

Pattern rules

Rules that use the % character define a pattern for matching targets and prerequisites. This is a powerful generalization of the original make's suffix rules. Many of GNU make's built-in rules are pattern rules. For example, this built-in rule is used to compile C programs into relocatable object files:

    %.o : %.c

            $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@

Each target listed in a pattern rule must contain only one % character. To match these rules, files must have at least one character in their names to match the %; a file named just .o would not match the above rule. The text that matches the % is called the stem, and the stem's value is substituted for the % in the prerequisite. (Thus, for example, prog.c becomes the prerequisite for prog.o.)

Conditional statements

Statements that evaluate conditions, and depending upon the result, include or exclude other statements from the contents of the makefile. More detail is given in the section "Conditional Input," later in this chapter.

Macro definitions

Macro definitions define variables: identifiers associated with blocks of text. Variable values can be created with either =, :=, or define, and appended to with +=. More detail is provided in the later section "Creating and Using Macros."

include statements

Similar to the C #include directive, there are three forms:

    include file [file ...]

    -include file [file ...]

    sinclude file [file ...]

make processes the value of file for macro expansions before attempting to open the file. Furthermore, each file may be a shell-style wildcard pattern, in which case make expands it to produce a list of files to read.

The second and third forms have the same meaning. They indicate that make should try to include the named lines, but should continue without an error if a file could not be included. The sinclude version provides compatibility with other versions of make.

vpath statements

Similar to the VPATH variable, the vpath line has one of the following three forms:

    vpath pattern directory ...      Set directory list for pattern

    vpath pattern                    Clear list for pattern

    vpath                            Clear all lists

Each pattern is similar to those for pattern rules, using % as a wildcard character. When attempting to find a prerequisite, make looks for a vpath rule that matches the prerequisite, and then searches in the directory list (separated by spaces or colons) for a matching file. Directories provided with vpath directives are searched before those provided by the VPATH variable.

Command lines

These lines are where you give the commands to actually rebuild those files that are out of date. Commands are grouped below the dependency line and are typed on lines that begin with a tab. If a command is preceded by a hyphen (-), make ignores any error returned. If a command is preceded by an at sign (@), the command line won't echo on the display (unless make is called with -n). Lines beginning with a plus (+) are always executed, even if -n, -q, or -t are used. This also applies to lines containing $(MAKE) or ${MAKE}. Further advice on command lines is given later in this chapter.

16.3.1. Special Dependencies

GNU make has two special features for working with dependencies.

Library dependencies

A dependency of the form -lNAME causes make to search for a library file whose name is either libNAME.so or libNAME.a in the standard library directories. This is customizable with the .LIBPATTERNS variable; see the later section "Macros with Special Handling" for more information.

Order-only prerequisites

When a normal prerequisite of a target is out of date, two things happen. First, the prerequisite (and its prerequisites, recursively) are rebuilt as needed. This imposes an ordering on the building of targets and prerequisites. Second, after the prerequisites are updated, the target itself is rebuilt using the accompanying commands. Normally, both of these are what's desired.

Sometimes, you just wish to impose an ordering, such that the prerequisites are themselves updated, but the target is not rebuilt by running its rules. Such order-only prerequisites are specified in a dependency line by placing them to the right of a vertical bar or pipe symbol, |:

    target: normal-dep1 normal-dep2 | order-dep1 order-dep2

            command

Dependency lines need not contain both. I.e., you do not have to provide regular dependencies if there are order-only dependencies as well; just place the | right after the colon.

Here is an annotated example of an order-only dependency:

    $ cat Makefile

    all: target                        First target is default, point to real target

    prereq0:                           How to make prereq0

            @echo making prereq0

            touch prereq0

    prereq1:                           How to make prereq1

            @echo making prereq1

            touch prereq1

    prereq2: prereq0                   prereq2 depends on prereq0

            @echo making prereq2

            touch prereq2

    target: prereq1 | prereq2          How to make target

            @echo making target

            touch target

The order of creation is shown in Figure 16-1.

Figure 16-1. The order of creation

And here is the result of running make:

    $ make

    making prereq1

    touch prereq1

    making prereq0

    touch prereq0

    making prereq2

    touch prereq2

    making target

    touch target

This is normal and as expected. Now, let's update one of the order-only prerequisites and rerun make:

    $ touch prereq0

    $ make

    making prereq2

    touch prereq2

Note that target was not rebuilt! Had the dependency on prereq2 been a regular dependency, then target itself would also have been remade.

16.3.2. Conditional Input

Conditional statements allow you to include or exclude specific lines based on some condition. The condition can be that a macro is or is not defined, or that the value of a macro is or is not equal to a particular string. The equivalence/nonequivalence tests provide three different ways of quoting the values. Conditionals may have an optional "else" part; i.e., lines that are used when the condition is not true. The general form is as follows:

    ifXXX test

        lines to include if true

    [ else

        lines to include if false ]

    endif

(The square brackets indicate optional parts of the construct; they are not to be entered literally.) Actual tests are as follows:

Condition | Meaning
ifdef macroname | True if macroname is a macro that has been given a value.
ifndef macroname | True if macroname is a macro that has not been given a value.
ifeq (v1,v2) |
ifeq 'v1' 'v2' | True if values v1 and v2 are equal.
ifeq "v1" "v2" |
ifneq (v1,v2) |
ifneq 'v1' 'v2' | True if values v1 and v2 are not equal.
ifneq "v1" "v2" |

For example:

    whizprog.o: whizprog.c

    ifeq($(ARCH),ENIAC)      # Serious retrocomputing in progess!

            $(CC) $(CFLAGS) $(ENIACFLAGS) -c $< -o $@

    else

            $(CC) $(CFLAGS) -c $< -o $@

    endif


16.4. Macros

This section summarizes creating and using macros , internal macros, macro modifiers, macros with special handling, and text manipulation with macros and functions.

16.4.1. Creating and Using Macros

Macros (often called variables) are like variables in a programming language. In make, they are most similar to variables in the shell language, having string values that can be assigned, referenced, and compared.

16.4.1.1. Defining macros

GNU make provides multiple ways to define macros. The different mechanisms affect how make treats the value being assigned. This in turn affects how the value is treated when the macro's value is retrieved, or referenced. GNU make defines two types of variables, called recursively expanded variables and simply expanded variables, respectively. The various macro assignment forms are as follows:

name = value

Create a recursively expanded variable. The value of name is the verbatim text on the right side of the =. If this value contains any references to other variable values, those values are retrieved and expanded when the original variable is referenced. For example:

    bar = v1

    foo = $(bar)            Value of bar retrieved when foo's value is referenced

    ...

    x = $(foo)              x is assigned 'v1'

    bar = v2

    y = $(foo)              y is assigned 'v2'

name := value

Create a simply expanded variable. The value is expanded completely, immediately at the time of the assignment. Any variable references in value are expanded then and there. For example:

    bar = v1

    foo := $(bar)           foo is assigned 'v1'

    x = $(foo)              x is assigned 'v1'

    bar = v2

    y = $(foo)              y is still assigned 'v1'

A significant advantage of simply expanded variables is that they work like variables in most programming languages, allowing you to use their values in assignments to themselves:

    x := $(x) other stuff

name += value

Append value to the contents of variable name. If name was never defined, += acts like =, creating a recursively defined variable. Otherwise, the result of += depends upon the type of name. If name was defined with =, then value is appended literally to the contents of name. However, if name was defined with :=, then make completely expands value before appending it to the contents of name.

name ?= value

Create recursively expanded variable name with value value only if name is not defined. Note that a variable that has been given an empty value is still considered to be defined.

define name

...

endef

Define a recursively expanded variable, similar to =. However, using define, you can give a macro a value that contains one or more newlines. This is not possible with the other assignment forms (=, :=, +=, ?=).

16.4.1.2. Macro values

Macro values are retrieved by prefixing the macro name with a $. A plain $ is enough for macros whose names are a single character, such as $< and $@. However, macro names of two or more characters must be enclosed in parentheses and preceded by a $. For example, $(CC), $(CPP), and so on.

Although it was not documented, the original V7 Unix version of make allowed the use of curly braces instead of parentheses: ${CC}, ${RM}, and so on.[*] All Unix versions and GNU make support this as well, and it is included in POSIX. This usage was particularly common in makefiles in the BSD distributions. There is no real reason to prefer one over the other, although long-time Unix programmers may prefer the parentheses form, since that is what was originally documented.

[*] See the function subst( ) in http://minnie.tuhs.org/UnixTree/V7/usr/src/cmd/make/misc.c.html.

16.4.1.3. Exporting macros

By default, make exports variables to subprocesses only if those variables were already in the environment or if they were defined on the command line. Furthermore, only variables whose names contain just letters, digits, and underscores are exported, as many shells cannot handle environment variables with punctuation characters in their names. You can use the export directive to control exporting of specific variables, or all variables. The unexport directive indicates that a particular variable should not be exported; it cancels the effect of a previous export command. The command forms are as follows:

export

By itself, the export directive causes make to export all alphanumerically named variables to the environment (where underscore counts as a letter too).

export var

Export variable var to the environment. The variable will be exported even if its name contains nonalphanumeric characters.

export var = value

export var := value

export var += value

export var ? value

Perform the kind of assignment indicated by the given operator (as described earlier), and then export the variable to the environment.

unexport var

Do not export variable var to the environment. Cancels a previous export of var (for example, from a separate, included makefile).

16.4.1.4. Overriding command-line macros

Normally, when a macro is defined on the command line, the given value is used, and any value assigned to the macro within the makefile is ignored. Occasionally, you may wish to force a variable to have a certain value, or to append a value to a variable, no matter what value was given on the command line. This is the job of the override directive.

override var = value

override var := value

override var += value

override var ? value

override define name

...

endef

Perform the kind of assignment indicated by the given operator (as described earlier), and then export the variable to the environment.

The example given in the GNU make documentation, GNU Make: A Program for Directing Recompilation, is forcing CFLAGS to always contain the -g option:

    override CFLAGS += -g

16.4.2. Internal Macros

$? | The list of prerequisites that have been changed more recently than the current target. Can be used only in normal makefile entries—not suffix rules.
$@ | The name of the current target, except in makefile entries for making libraries, where it becomes the library name. (For libguide.a(dontpanic.o), $@ is libguide.a). Can be used both in normal makefile entries and in suffix rules.
$$@ | The name of the current target. Can be used only to the right of the colon in dependency lines. This is provided only for compatibility with System V make; its use is not recommended.
$< | The name of the current prerequisite that has been modified more recently than the current target.
$* | The name—without the suffix—of the current prerequisite that has been modified more recently than the current target. Should be used only in implicit rules or static pattern rules.
$% | The name of the corresponding .o file when the current target is a library module. (For libguide.a(dontpanic.o), $% is dontpanic.o). Can be used both in normal makefile entries and in suffix rules.
$^ | The list of prerequisites for the current target. For archive members, only the member name is listed. Even if a prerequisite appears multiple times in a dependency list for a target, it only appears once in the value of $^.
$+ | Like $^, but prerequisites that appear multiple times in a dependency list for a target are repeated. This is most useful for libraries, since multiple dependencies upon a library can make sense and be useful.
$$ | A literal $ for use in rule command lines: for example, when referencing shell variables in the environment or within a loop.
$| | The order-only prerequisites for the current target.

16.4.3. Macro Modifiers

Macro modifiers may be applied to the built-in internal macros listed earlier, except for $$.

D

The directory portion of any internal macro name. Valid uses are:

    $(%D)     $(@D)

    $(*D)     $$(@D)

    $(<D)     $(^D)

    $(?D)     @(+D)

F

The file portion of any internal macro name. Valid uses are:

    $(%F)     $(@F)

    $(*F)     $$(@F)

    $(<F)     $(^F)

    $(?F)     @(+F)

16.4.4. Macros with Special Handling

CURDIR

The current working directory. Set by make but not used by it, for use in makefiles.

.LIBPATTERNS

Used for finding link library names as prerequisites of the form -lname. For each such prerequisite, make searches in the current directory, directories matching any vpath directives, directories named by the VPATH variable, /lib, /usr/lib, and prefix/lib, where prefix is the installation directory for GNU make (normally /usr/local).

The default value of .LIBPATTERNS is lib%.so lib%.a. Thus make first searches for a shared library file, and then for a regular archive library.

MAKE

The full pathname used to invoke make. It is special because command lines containing the string $(MAKE) or ${MAKE} are always executed, even when any of the -n, -q, or -t options are used.

MAKECMDGOALS

The targets given to make on the command line.

MAKEFILE_LIST

A list of makefiles read so far. The rightmost entry in the list is the name of the makefile currently being read.

MAKEFILES

Environment variable: make reads the whitespace-separated list of files named in it before reading any other makefiles.

MAKEFLAGS

Contains the flags inherited in the environment variable MAKEFLAGS, plus any command-line options. Used to pass the flags to subsequent invocations of make, usually via command lines in a makefile entry that contain $(MAKE).

MAKELEVEL

The depth of recursion (sub-make invocation). Primarily for use in conditional statements so that a makefile can act in one way as the top-level makefile and in another way if invoked by another make.

OVERRIDES

A list of the command-line variable definitions. MAKEFLAGS refers to this variable. By setting it to the empty string:

    MAKEOVERRIDES =

You can pass down the command-line options to sub-makes but avoid passing down the variable assignments.

MAKESHELL

For MS-DOS only, the shell make should use for running commands.

MFLAGS

Similar to MAKEFLAGS, this variable is set for compatibility with other versions of make. It contains the same options as in MAKEFLAGS, but not the variable settings. It was designed for explicit use on command lines that invoke make. For example:

    mylib:

            cd mylib && $(MAKE) $(MFLAGS)

The use of MAKEFLAGS is preferred.

SHELL

Sets the shell that interprets commands. If this macro isn't defined, the default is /bin/sh. On MS-DOS, if SHELL not set, the value of COMSPEC is used; see also the MAKESHELL variable, earlier in this list.

SUFFIXES

The default list of suffixes, before make reads and processes makefiles.

.VARIABLES

A list of all variables defined in all makefiles read up to the point that this variable is referenced.

VPATH

Specifies a list of directories to search for prerequisites when not found in the current directory. Directories in the list should be separated with spaces or colons.

16.4.5. Text Manipulation with Macros and Functions

Standard versions of make provide a limited text manipulation facility:

$( macro: s1= s2)

Evaluates to the current definition of $(macro), after substituting the string s2 for every occurrence of s1 that occurs either immediately before a blank or tab, or at the end of the macro definition.

GNU make supports this for compatibility with Unix make and the POSIX standard. However, GNU make goes far beyond simple text substitution, providing a host of functions for text manipulation. The following list provides a brief description of each function.

$(addprefix prefix, names ...)

Generates a new list, created by prepending prefix to each of the names.

$(addsuffix suffix, names ...)

Generates a new list, created by appending suffix to each of the names.

$(basename names ...)

Returns a list of the basename of each of the names. The basename is the text up to but not including the final period.

$(call var, param, ...)

The call function allows you to treat the value of a variable as a procedure. var is the name of a variable, not a variable reference. The params are assigned to temporary variables that may be referenced as $(1), $(2), and so on. $(0) will be the name of the variable. The value of var should reference the temporary values. The result of call is the result of evaluating var in this way. If var names a built-in function, that function is always called, even if a make variable of the same name exists. Finally, call may be used recursively; each invocation gets its own $(1), $(2), and so on.

$(dir names ...)

Returns a list of the directory part of each of the names. The directory part is all text, up to and including the final / character. If there is no /, the two characters ./ are used.

$(error text ...)

Causes make to produce a fatal error message consisting of text.

$(filter pattern ..., text)

Chooses the words in text that match any pattern. Patterns are written using %, as for the patsubst function.

$(filter-out pattern ..., text)

Like filter, but selects the words that do not match the patterns.

$(findstring find, text)

Searches text for an instance of find. If found, the result is find; otherwise, it's the empty string.

$(firstword names ...)

Returns the first word in names.

$(foreach var, words, text)

This function is similar to the for loop in the shell. It expands var and words, first. The result of expanding var names a macro. make then loops, setting var to each word in words, and then evaluating text. The result is the concatenation of all the iterations. The text should contain a reference to the variable for this to work correctly.

If var is defined before the foreach is evaluated, it maintains the same value it had after the evaluation. If it was undefined before the foreach, it remains undefined afterwords. In effect, foreach creates a temporary, private variable named var.

$(if condition, then-text[, else-text])

The condition is evaluated. If, after removing leading and trailing whitespace, the result is not empty, the condition is considered to be true, and the result of if is the expansion of the then-text. Otherwise, the condition is considered to be false, and the result is the expansion of else-text, if any. If there's no else-text, then a false condition produces the empty string. Only one or the other of then-text and else-text is evaluated.

$(join list1, list2)

Produces a new list where the first element is the concatenation of the first elements in list1 and list2, the second element is the concatenation of the second elements in list1 and list2, and so on.

$(notdir names ...)

Returns a list of the nondirectory part of each of the names. The nondirectory part is all the text after the final /, if any. If not, it's the entire name.

$(origin variable)

Returns a string describing the origin of variable. Here, variable is a variable name (foo), not a variable reference ($(foo)). Possible return values are one of the following:

automatic

The variable is an automatic variable for use in the commands of rules, such as $* and $@.

command line

The variable was defined on the command line.

default

The variable is one of those defined by make's built-in rules, such as CC.

environment

The variable was defined in the environment, and -e was not used.

environment override

The variable was defined in the environment, and -e was used.

file

The variable was defined in a makefile.

override

The variable was defined with an override command. See the earlier section "Overriding command-line macros."

undefined

The variable was never given a value.

$(patsubst pattern, replacement, text)

Replaces words in text that match pattern with replacement. The pattern should use a % as a wildcard character. In replacement, a % acts as the placeholder for the text that matched the % in pattern. This is a general form of string substitution. For example, the traditional OBJS = $(SRCS:.c=.o) could instead be written OBJS = $(patsubst %.c, %.o, $(SRCS)).

$(shell command)

Runs the shell command command and returns the output. make converts newlines in the output into spaces and removes trailing newlines. This is similar to '...' in the shell.

$(sort list)

Returns a sorted copy of the words in list, with duplicates removed. Each word is separated from the next by a single space.

$(subst from, to, text)

Replaces every instance of from in text with to.

$(suffix names ...)

Returns a list of the suffixes of each name. The suffix is the final period and any following text. Returns an empty string for a name without a period.

$(strip string)

Removes leading and trailing whitespace from string and converts internal runs of whitespace into single spaces. This is especially useful in conjunction with conditionals.

$(warning text ...)

Causes make to produce a warning message consisting of text.

$(wildcard pattern ...)

Creates a space-separated list of filenames that match the shell pattern pattern. (Note! Not a make-style % pattern.)

$(word n, text)

Returns the nth word of text, counting from one.

$(wordlist start, end, text)

Creates a new list consisting of the words start to end in text. Counting starts at one.

$(words text)

Returns the number of words in text.


16.5. Special Target Names

.DEFAULT: | Commands associated with this target are executed if make can't find any makefile entries or suffix rules with which to build a requested target.
.DELETE_ON_ERROR: | If this target appears in a makefile, then for any target that make is rebuilding, if its command(s) exit with a nonzero status, make deletes the target.
.EXPORT_ALL_VARIABLES: | The mere existence of this target causes make to export all variables to child processes.
.IGNORE: | With prerequisites, ignore problems just for those files. For historical compatibility, with no prerequisites, ignore error returns from all commands. This is the same as the -i option.
.INTERMEDIATE: | Prerequisites for this target are treated as intermediate files, even if they are mentioned explicitly in other rules. (An intermediate file is one that needs to be built "along the way" to the real target. For example, making a .c file from a .y file, in order to create a .o object file. The .c file is an intermediate file.) This prevents them from being re-created, unless one of their prerequisites is out of date.
.LOW_RESOLUTION_TIME: | make notes that prerequisites for this target are updated by commands that only create low resolution timestamps (one second granularity). For such targets, if their modification time starts at the same second as the modification time of a prerequisite, make does not try to compare the sub-second time values, and does not treat the file as being out of date.
.NOTPARALLEL: | Prerequisites for this target are ignored. Its existence in a makefile overrides any -j option, forcing all commands to run serially. Recursive make invocations may still run jobs in parallel, unless their makefiles also contain this target.
.POSIX: | When this target exists, changing the MAKEOVERRIDES variable does not affect the MAKEFLAGS variable. (This is a rather specialized case.) This target also disables the special treatment of $$@, $$(@D), and $$(@F).
.PHONY: | Prerequisites for this target are marked as "phony." I.e., make always executes their rules, even if a file by the same name exists.
.PRECIOUS: | Files you specify for this target are not removed when you send a signal (such as interrupt) that aborts make, or when a command line in your makefile returns an error.
.SECONDARY: | Prerequisites of this target are treated like intermediate files, except that they are never automatically removed. With no prerequisites, all targets are treated as secondary.
.SILENT: | When given prerequisites, make will not print the commands for those prerequisites when they are rebuilt. Otherwise, for historical compatibility, when this target has no prerequisites, make executes all commands silently, which is the same as the -s option.
.SUFFIXES: | Suffixes associated with this target are meaningful in suffix rules. If no suffixes are listed, the existing suffix rules are effectively "turned off."


16.6. Writing Command Lines

Writing good, portable makefile files is a bit of an art. Skill comes with practice and experience. Here are some tips to get you started:

  • Depending upon your locale, naming your file Makefile instead of makefile can cause it to be listed first with ls. This makes it easier to find in a directory with many files.

  • Remember that command lines must start with a leading tab character. You cannot just indent the line with spaces, even eight spaces. If you use spaces, make exits with an unhelpful message about a "missing separator."

  • Remember that $ is special to make. To get a literal $ into your command lines, use $$. This is particularly important if you want to access an environment variable that isn't a make macro. Also, if you wish to use the shell's $$ for the current process ID, you have to type it as $$$$.

  • Write multiline shell statements, such as shell conditionals and loops, with trailing semicolons and a trailing backslash:

    if [ -f specfile ] ; then \

    ... ; \

    else \

    ... ; \

    fi

    Note that the shell keywords then and else don't need the semicolon. (What happens is that make passes the backslashes and the newlines to the shell. The escaped newlines are not syntactically important, so the semicolons are needed to separate the different parts of the command. This can be confusing. If you use a semicolon where you would normally put a newline in a shell script, things should work correctly.)

  • Remember that each line is run in a separate shell. This means that commands that change the shell's environment (such as cd) are ineffective across multiple lines. The correct way to write such commands is to keep the commands on the same line, separated with a semicolon. In the particular case of cd, separate the commands with && in case the subdirectory doesn't exist or can't be changed to:

    cd subdir && $(MAKE)

    ...

    PATH=special-path-value ; export PATH ; $(MAKE)

  • For guaranteed portability, always set SHELL to /bin/sh. Some versions of make use whatever value is in the environment for SHELL, unless it is explicitly set in the makefile.

  • Use macros for standard commands. make already helps out with this, providing macros such as $(CC), $(YACC), and so on.

  • When removing files, start your command line with -$(RM) instead of $(RM). (The - causes make to ignore the exit status of the command.) This way, if the file you were trying to remove doesn't exist, and rm exits with an error, make can keep going.

  • When running subsidiary invocations of make, typically in subdirectories of your main program tree, always use $(MAKE), and not make. Lines that contain $(MAKE) are always executed, even if -n has been provided, allowing you to test out a whole hierarchy of makefiles. This does not happen for lines that invoke make directly.

  • Often, it is convenient to organize a large software project into subprojects, with each one having a subdirectory. The top-level makefile then just invokes make in each subdirectory. Here's the way to do it:

    SUBDIRS = proj1 proj2 proj3

    ...

    projects: $(SUBDIRS)

            for i in $(SUBDIRS); \

            do \

                    echo ====== Making in $$i ; \

                    ( cd $$i && $(MAKE) $(MAKEFLAGS) $@ ) ; \

            done


Chapter 17. The GDB Debugger

The GNU Debugger, GDB, is the standard debugger on GNU/Linux and BSD systems, and can be used on just about any Unix system with a C compiler and at least one of several well-known object file formats. It can be used on other kinds of systems as well. It has a very rich feature set, making it the preferred debugger of many developers the world over.

This chapter covers the following topics:

  • Conceptual overview

  • Command-line syntax

  • Initialization files

  • GDB expressions

  • The GDB text user interface

  • Group listing of GDB commands

  • Summary of set and show commands

  • Summary of info command

  • Alphabetical summary of GDB commands

For more information, see Debugging with GDB: The GNU Source-Level Debugger, listed in the Bibliography.


17.1. Conceptual Overview

A debugger is a program that lets you run a second program, which we will call the debuggee. The debugger lets you examine and change the state of the debuggee, and control its execution. In particular, you can single-step the program, executing one statement or instruction at a time, in order to watch the program's behavior.

Debuggers come in two flavors: instruction-level debuggers , which work at the level of machine instructions, and source-level debuggers , which operate in terms of your program's source code and programming language. The latter are considerably easier to use, and usually can do machine-level debugging if necessary. GDB is a source level debugger; it is probably the most widely applicable debugger (portable to the largest number of architectures) of any current debugger.

GDB itself provides two user interfaces : the traditional command-line interface (CLI) and a text user interface (TUI). The latter is meant for regular terminals or terminal emulators, dividing the screen into separate "windows" for the display of source code, register values, and so on.

GDB provides support for debugging programs written in C, C++, Objective C, Java,[*] and Fortran. It provides partial support for Modula-2 programs compiled with the GNU Modula-2 compiler and for Ada programs compiled with the GNU Ada Translator, GNAT. GDB provides some minimal support for debugging Pascal programs. The Chill language is no longer supported.

[*] GDB can only debug Java programs that have been compiled to native machine code with GJC, the GNU Java compiler (part of GCC, the GNU Compiler Collection).

When working with C++ and Objective C, GDB provides name demangling . C++ and Objective C encode overloaded procedure names into a unique "mangled" name that represents the procedure's return type, argument types, and class membership. This ensures so-called type-safe linkage . There are different methods for name mangling, thus GDB allows you to select among a set of supported methods, besides just automatically demangling names in displays.

If your program is compiled with GCC (the GNU Compiler Collection), using the -g3 and -gdwarf-2 options, GDB understands references to C preprocessor macros . This is particularly helpful for code using macros to simplify complicated struct and union members. GDB itself also has partial support for expanding preprocessor macros, with more support planned.

GDB allows you to specify several different kinds of files when doing debugging:

  • The exec file is the executable program to be debugged—i.e., your program.

  • The optional core file is a memory dump generated by the program when it dies; this is used, together with the exec file, for post-mortem debugging. Core files are usually named core on commercial Unix systems. On BSD systems, they are named program.core. On GNU/Linux systems, they are named core.PID, where PID represents the process ID number. This lets you keep multiple core dumps, if necessary.

  • The symbol file is a separate file from which GDB can read symbol information: information describing variable names, types, sizes, and locations in the executable file. GDB, not the compiler, creates these files if necessary. Symbol files are rather esoteric; they're not necessary for run-of-the-mill debugging.

There are different ways to stop your program:

  • A breakpoint specifies that execution should stop at a particular source code location.

  • A watchpoint indicates that execution should stop when a particular memory location changes value. The location can be specified either as a regular variable name or via an expression (such as one involving pointers). If hardware assistance for watchpoints is available, GDB uses it, making the cost of using watchpoints small. If it is not available, GDB uses virtual memory techniques, if possible, to implement watchpoints. This also keeps the cost down. Otherwise, GDB implements watchpoints in software by single-stepping the program (executing one instruction at a time).

  • A catchpoint specifies that execution should stop when a particular event occurs.

The GDB documentation and command set often use the word breakpoint as a generic term to mean all three kinds of program stoppers . In particular, you use the same commands to enable, disable, and remove all three.

GDB applies different statuses to breakpoints (and watchpoints and catchpoints ). They may be enabled, which means that the program stops when the breakpoint is hit (or fires), disabled, which means that GDB keeps track of them but that they don't affect execution, or deleted, which means that GDB forgets about them completely. As a special case, breakpoints can be enabled only once. Such a breakpoint stops execution when it is encountered, then becomes disabled (but not forgotten).

Breakpoints may have conditions associated with them. When execution reaches the breakpoint, GDB checks the condition, stopping the program only if the condition is true.

Breakpoints may also have an ignore count, which is a count of how many times GDB should ignore the breakpoint when it's reached. As long as a breakpoint's ignore count is nonzero, GDB does not bother checking any condition associated with the breakpoint.

Perhaps the most fundamental concept for working with GDB is that of the frame. This is short for stack frame, a term from the compiler field. A stack frame is the collection of information needed for each separate function invocation. It contains the function's parameters and local variables, as well as linkage information indicating where return values should be placed and the location the function should return to. GDB assigns numbers to frames, starting at 0 and going up. Frame 0 is the innermost frame, i.e., the function most recently called.

GDB uses the readline library, as does the Bash shell, to provide command history, command completion, and interactive editing of the command line. Both Emacs and vi style editing commands are available.

Finally, GDB has many features of a programming language. You can define your own variables and apply common programming language operators to them. You can also define your own commands. Additionally, you can define special hook commands, user-defined commands that GDB executes before or after running a built-in command. (See the entry for define in the section "Alphabetical Summary of GDB Commands" for the details.) You can also create while loops and test conditions with if ... else ... end.

GDB is typically used to debug programs on the same machine (host) on which it's running. GDB can also be configured for cross-debugging, i.e., controlling a remote debuggee with a possibly different machine architecture (the target). Remote targets are usually connected to the host via a serial port or a network connection. Such use is rather esoteric and is therefore not covered here. See the GDB documentation for the full details.

17.1.1. Source Code Locations

GDB is the default debugger on GNU/Linux and BSD systems. It is usable on just about any modern Unix system, though, as well as many older ones. (However, if your system is really ancient, you may need to fall back to an older version of GDB.) Besides the command line and text user interfaces built in to GDB, there are other programs that provide GUI debuggers. Two of the more popular ones are ddd (the Data Display Debugger) and Insight . Both of these use GDB to provide the underlying debugging functionality. Source code URLs for these programs are listed in the following table.

Debugger | Location
ddd | ftp://ftp.gnu.org/gnu/ddd/
GDB | ftp://ftp.gnu.org/gnu/gdb/
Insight | http://sources.redhat.com/insight/


17.2. Command-Line Syntax

GDB is invoked as follows:

    gdb [options] [executable [corefile-or-PID]]

    gdb [options] --args executable [program args ...]

The gdbtui command is equivalent to gdb --tui; it invokes GDB with the Text User Interface. The TUI is described in the later section "The GDB Text User Interface."

GDB has both traditional short options and GNU-style long options. Long options may start with either one or two hyphens. The command-line options are as follows.

--args

Pass on arguments after executable to the program being debugged.

--async, --noasync

Enable/disable the asynchronous version of the command-line interface.

-b baudrate, --baud baudrate

Set the serial port baud rate used for remote debugging.

--batch

Process options and then exit.

--cd dir

Change current directory to dir.

-c file, --core file

Analyze the core dump file.

-d dir, --directory dir

Search for source files in dir.

-e file, --exec file

Use file as the executable.

-f, --fullname

Output information used by the Emacs-GDB interface.

--help

Print a usage and option summary and then exit.

--interpreter interp

Select a specific interpreter/user interface. The command-line interface is the default, although there are other interfaces for use by frontend programs.

-n, --nx

Do not read the .gdbinit file.

-nw, --nowindows

Force the use of the command-line interface, even if a windows interface is available.

-p pidnum, -c pidnum, --pid pidnum

Attach to running process pidnum.

-q, --quiet, --silent

Do not print the version number on startup.

-r, --readnow

Fully read symbol files on first access.

-s file, --symbols file

Read symbols from file.

--se file

Use file for both the symbol file and the executable file.

--statistics

Print statistics about CPU time and memory usage after each command finishes.

-t device, --tty device

Use device for input/output by the program being debugged.

--tui

Use the Terminal User Interface (TUI).

-x file, --command file

Execute GDB commands from file.

--version

Print version information and then exit.

-w, --windows

Force the use of a window interface if there is one.

--write

Allow writing into the executable and core files.


17.3. Initialization Files

Two files are used to initialize GDB and the readline library, respectively.

17.3.1. The .gdbinit File

At startup, GDB reads its initialization file. This is a file of commands, such as option settings, that you tell GDB to run every time it starts up. The initialization file is named .gdbinit on Unix (BSD, Linux, etc.) systems. Some MS-Windows versions of GDB use gdb.ini instead. Empty lines (they do nothing) are allowed, and comments in initialization files start with a # and continue to the end of the line. GDB executes commands from initialization files and from the command line in the following order:

  1. Commands in $HOME/.gdbinit. This acts as a "global" initialization; settings that should always be used go here.

  2. Command-line options and operands.

  3. Commands in ./.gdbinit. This allows for option settings that apply to a particular program by keeping the file in the same directory as the program's source code.

  4. Command files specified with the -x option.

You may use the -nx option to make GDB skip the execution of the initialization files.

17.3.2. The .inputrc File

Just like the Bash shell (see Chapter 4), GDB uses the readline library to provide command-line history and editing. You may use either vi- or Emacs-style commands for editing your command line. The readline library reads the file ~/.inputrc to initialize its settings and options. The details are beyond the scope of this book; see the Bash and GDB documentation or the online Info system for the full story. Here is a sample .inputrc file:

    set editing-mode vi                Use vi editor commands

    set horizontal-scroll-mode On      Scroll line left/right as cursor moves along it

    control-h: backward-delete-char    Use ^H as backspace character

    set comment-begin #                For Bash, # starts comments

    set expand-tilde On                Expand ~ notation

    "\C-r": redraw-current-line        Make ^R redraw the current input line


17.4. GDB Expressions

GDB can be thought of as a specialized programming language. It has variables and operators similar to those of C, and special features for debugging. This section looks at the different kinds of expressions that GDB understands.

17.4.1. The Value History

Every time you print a value with print, GDB saves the value in the value history . You can reference these saved values by their numeric place in the history, preceded with a $. GDB reminds you of this by printing $n = val. For example:

    $ gdb whizprog

    ...

    (gdb) print stopped_early

    $1 = 0

    (gdb) print whiny_users

    $2 = TRUE

    (gdb)

A plain $ refers to the most recent value in the value history. This can save considerable typing. If you've just looked at a pointer variable, you can use:

    (gdb) print *$

to print the contents of whatever the pointer is pointing to. $$ refers to the next most recent value in the history, and $$n refers to the value n places from the end. (Thus, $n counts from the beginning, while $$n counts from the end.)

You can use show values to see the values in the history. Whenever GDB reloads the executable (rereads the symbol table), it clears the value history. This is because the value history may have contained pointers into the symbol table and such pointers become invalid when the symbol table is reloaded.

17.4.2. Convenience Variables and Machine Registers

GDB lets you create convenience variables . These are variables you can use to store values as you need them. Their names begin with a $ and consist of alphanumeric characters and underscores. They should start with a letter or underscore. (Note that values in the value history have names that are numeric.) You might want to use a convenience variable as an array index:

    (gdb) set $j = 0

    (gdb) print data[$j++]

After these two commands, simply hitting the ENTER key repeats the last command, stepping through the array one element at a time.

GDB predefines several convenience variables. It also enables you to access the machine registers using predefined register names. Register names vary with machine architecture, of course, but there are four predefined registers available on every architecture. The following list summarizes the convenience variables and predefined registers. The last four entries in the list are the registers that are always available.

$ | The most recent value in the value history.
$n | Item n in the value history.
$$ | The next to last item in the value history.
$$n | Item n in the value history, counting from the end.
$_ | The address last printed by the x command.
$_ _ | The contents of the address last printed by the x command.
$_exitcode | The exit status that the debuggee returned when it exited.
$bpnum | The breakpoint number of the most recently set breakpoint.
$cdir | The compilation directory for the current source file, if one is recorded in the object file.
$cwd | The current working directory.
$fp | The frame pointer register.
$pc | The program counter register.
$ps | The processor status register.
$sp | The stack pointer register.

17.4.3. Special Expressions

GDB understands the syntax (types, operators, operator precedence) of the language being debugged. You can use the same syntax to enter expressions as you do to modify GDB convenience variables (such $i++). GDB also understands several special syntaxes that let you do things that are not in the target language, as follows:

Array constants

You can create an array constant in the debuggee's memory by enclosing a list of element values in braces. For example, { 1, 2, 3, 42, 57 }.

Array operator

The @ array operator prints all the elements of an array up to a given subscript. For example, if your program uses malloc( ) to allocate memory:

    double *vals = malloc(count * sizeof(double));

you can print a single element using regular subscripting:

    (gdb) print vals[3]

    $1 = 9

However, you can access vals[0] through vals[2] with:

    (gdb) print *vals@3

    $2 = {0, 1, 4}

File resolution

If you use the same variable name in several source files (for example, each one is static), you can specify which one you mean using file::variable. For example:

    (gdb) print 'main.c'::errcount

    $2 = 0

It is necessary to put main.c in single quotes to avoid ambiguity with the C++ :: operator.


17.5. The GDB Text User Interface

GDB , in its default mode, shows its line-oriented heritage. When single stepping, it displays only one line of source code at a time. Graphical debuggers can show you much more, and indeed many programmers prefer a graphical debugger, if only for this reason. However, recent versions of GDB offer a Text User Interface (TUI), which uses the tried-and-true curses library to provide several "windows" on a regular terminal or terminal emulator, such as an xterm. This can be quite effective, especially since it allows you to do everything from the keyboard.

A number of set options and GDB commands are specific to the TUI. These are listed along with the rest of the set options and GDB commands in the later sections "Summary of set and show Commands" and "Alphabetical Summary of GDB Commands."

Unfortunately (as of GDB 6.3), the TUI is still immature; the author could not get several documented features to work. Thus this book doesn't provide detailed coverage of it. However, it should improve over time, and you should continue to evaluate it to see if it meets your needs.


17.6. Group Listing of GDB Commands

This section summarizes the GDB commands by task. Esoteric commands, such as those used by GDB's maintainers, or to cross-debug remote systems connected via serial port or a network, have been omitted.

17.6.1. Aliases for Other Commands

Alias | Short for... | Alias | Short for... | Alias | Short for...
bt | backtrace | f | frame | p | print
c | continue | fo | forward-search | po | print-object
cont | continue | gcore | generate-core-file | r | run
d | delete | h | help | s | step
dir | directory | i | info | share | sharedlibrary
dis | disable | l | list | si | stepi
do | down | n | next | u | until
e | edit | ni | nexti | where | backtrace

17.6.2. Breakpoints

awatch | Set an expression watchpoint.
break | Set a breakpoint at a line or function.
catch | Set a catchpoint to catch an event.
clear | Clear a given breakpoint.
commands | Specify commands to run when a breakpoint is reached.
condition | Supply a condition to a particular breakpoint.
delete | Delete one more breakpoints or auto-display expressions.
disable | Disable one or more breakpoints.
enable | Enable one or more breakpoints.
hbreak | Set a hardware assisted breakpoint.
ignore | Set the ignore-count of a particular breakpoint.
rbreak | Set a breakpoint for all functions matching a regular expression.
rwatch | Set a read watchpoint for an expression.
tbreak | Set a temporary breakpoint.
tcatch | Set a temporary catchpoint.
thbreak | Set a temporary hardware assisted breakpoint.
watch | Set an expression watchpoint.

17.6.3. Examining Data

call | Call a function in the program.
delete display | Cancel one or more expressions that have been set to display when the program stops.
delete mem | Delete a memory region.
disable display | Disable one or more expressions that have been set to display when the program stops.
disable mem | Disable a memory region.
disassemble | Disassemble a section of memory.
display | Print the value of an expression each time the program stops.
enable display | Enable one or more expressions that have been set to display when the program stops.
enable mem | Enable a memory region.
inspect | Same as print.
mem | Define attributes for a memory region.
output | Similar to print, but doesn't save the value in history and doesn't print a newline. For scripting.
print | Print the value of an expression.
print-object | Cause an Objective C object to print information about itself.
printf | Print values like the printf command.
ptype | Print the definition of a given type.
set | Evaluate an expression and save the result in a program variable.
set variable | Same as set, avoids conflict with GDB variables.
undisplay | Cancel one or more expressions that have been set to display when the program stops.
whatis | Print the data type of an expression.
x | Examine memory: x/fmt address. See the entry for x in the later section "Alphabetical Summary of GDB Commands."

17.6.4. Controlling and Examining Files

add-symbol-file

Add symbols from a dynamically loaded file to GDB's symbol table.

add-symbol-file-from-memory

Load the symbols from a dynamically loaded object file in the debuggee's memory.

cd

Set the current directory for GDB and the debuggee.

core-file

Specify a file to use as the core dump for memory and register contents.

directory

Add a directory to the beginning of the source file search path.

edit

Edit a file or function.

exec-file

Specify a file to use as the executable.

file

Specify the filename of the program to be debugged.

forward-search

Search forward in the current source file for a regular expression, starting at the last line listed.

generate-core-file

Create a core file from the current state of the debuggee.

list

List a function or line.

nosharedlibrary

Unload all shared object library symbols.

path

Add one or more directories to the object file search path.

pwd

Print the current directory.

reverse-search

Search backward in the current source file for a regular expression, starting at the last line listed.

search

Same as forward-search.

section

Change the base address of a particular section in the exec file.

sharedlibrary

Load shared object library symbols for files matching a regular expression.

symbol-file

Load symbol table information from a specified executable file.

17.6.5. Running a Program

advance | Continue the program up to the given location.
attach | Attach to a process or file outside of GDB.
continue | Continue the program being debugged.
detach | Detach a previously attached process or file.
finish | Execute until selected stack frame returns.
handle | Specify how to handle a signal.
interrupt | Interrupt the execution of the debugged program.
jump | Continue program being debugged at specified line or address.
kill | Kill the program being debugged.
next | Execute the program's next statement.
nexti | Execute the program's next instruction.
run | Start the debugged program.
signal | Continue the program, giving it a specified signal.
start | Run the debugged program until the beginning of the main procedure. Useful for C++ where constructors run before main( ).
step | Step the program until it reaches a different source line. Descends into called functions.
stepi | Step exactly one instruction.
thread | Switch between threads.
tHRead apply | Apply a command to a list of threads.
tHRead apply all | Apply a command to all threads.
tty | Set the terminal for future runs of the debuggee.
unset environment | Remove a variable from the debuggee's environment.
until | Execute until the program reaches a source line greater than the current one.

17.6.6. Examining the Stack

backtrace | Print a backtrace of all stack frames.
down | Select and print the stack frame called by the current one.
frame | Select and print a stack frame.
return | Make selected stack frame return to its caller.
select-frame | Select a stack frame without printing anything.
up | Select and print the stack frame that called the current one.

17.6.7. Status Inquiries

info | General command for showing information about the debuggee.
macro | Prefix for commands dealing with C preprocessor macros.
show | General command for showing information about the debugger.

17.6.8. Support Facilities

apropos | Search for commands matching a regular expression.
complete | List the command completions for the rest of the line.
define | Define a new command.
document | Document a user-defined command.
dont-repeat | Don't repeat this command. For use in user-defined commands.
down-silently | Same as the down command, but doesn't print messages.
echo | Print a constant string.
else | Provide a list of alternative commands for use with if.
end | End a list of commands or actions.
help | Print list of commands.
if | Execute nested commands once if the conditional expression is nonzero.
make | Run the make program using the rest of the line as arguments.
quit | Exit GDB.
shell | Execute the rest of the line as a shell command.
source | Read commands from a named file.
up-silently | Same as the up command, but doesn't print messages.
while | Execute nested commands while the conditional expression is nonzero.

17.6.9. Text User Interface Commands

focus | Change which window receives the keyboard focus.
layout | Change the layout of the windows in use.
refresh | Clear and redraw the screen.
tui reg | Change which registers are shown in the register window.
update | Update the source window.
winheight | Change the height of a particular window.

17.6.10. Frequently Used Commands

GDB offers a bewilderingly large number of commands, but most users can get by with just a small handful. Table 17-1 lists the ones that you are likely to use most often.

Table 17-1. The top dozen GDB commands

Command

Purpose

Examples

backtrace

Show call trace

ba

break

Set breakpoint at routine entry or at line number

b main

b parser.c:723

continue

Continue from breakpoint

cont

delete

Remove breakpoint

d 3

finish

Step until end of routine

fin

info breakpoints

List current breakpoints

i br

next

Step to next statement and over routine calls

ne

print

Print expression

print 1.0/3.0

run

(Re)run program, optionally with arguments

ru

ru -u -o foo < data

step

Step to next statement and into routines

s

x

Examine memory

x/s *environ

until

Continue execution until reaching a source line

until

until 2367


17.7. Summary of set and show Commands

The set command accepts a large number of different parameters that control GDB's behavior. Many of the accepted parameters are rather esoteric. The show command displays the values of the same parameters as set accepts. This section summarizes the parameters and how they affect GDB.

For most of the options, set option and set option on are equivalent; they enable the option. Use set option off to disable the option.

annotate

set annotate level

show annotate

Set the annotation_level variable to level. GUI programs that call GDB as a subsidiary process use this variable.

architecture

set architecture architecture

show architecture

Set the architecture of target to architecture. Primarily used in cross-debugging.

args

set args

show args

Give the debuggee the argument list when you start it. The run command uses this list when it isn't given any arguments. See the entry for run in the later section "Alphabetical Summary of GDB Commands."

auto-solib-add

set auto-solib-add

show auto-solib-add

Automatically load symbols from shared libraries as needed. When set to off, symbols must be loaded manually with the sharedlibrary command.

auto-solib-limit

set auto-solib-limit megs

show auto-solib-limit

Limit the size of symbols from shared libraries that will be automatically loaded to megs megabytes. Not available on all systems.

backtrace

set backtrace limit count

show backtrace limit

set backtrace past-main

show backtrace past-main

The first syntax limits the number of stack frames shown in a backtrace to count. The default is unlimited. The second syntax controls whether GDB shows information about frames that precede the main( ) function. Such startup code is usually not of interest, thus the default is off.

breakpoint

set breakpoint

 pending val

show breakpoint pending

How GDB should handle breakpoint locations that can't be found (for example, if a shared library has yet to be loaded). Values are on, off, or auto. When val is on, GDB automatically creates a pending breakpoint. For auto, it asks you. For off, pending breakpoints are not created.

can-use-hw-watchpoints

set can-use-hw-watchpoints value

show can-use-hw-watchpoints

If nonzero, GDB uses hardware support for watchpoints, if the system has such support. Otherwise, it doesn't.

case-sensitive

set case-sensitive

show case-sensitive

Set whether GDB should ignore case when searching for symbols. This variable can be set to on, off, or auto. For auto the case sensitivity depends upon the language.

coerce-float-to-double

set coerce-float-to-double

show coerce-float-to-double

When calling a function that is not prototyped, if this variable is on, GDB coerces values of type float to type double. If the variable is off, floats are not coerced to double and prototyped functions receive float values as is.

commands

show commands [cmdnum]

show commands +

By default, show the last 10 commands in the command history. With a numeric cmdnum, show the 10 commands centered around cmdnum. The second syntax shows the 10 commands following those just printed.

complaints

set complaints limit

show complaints

When GDB encounters problems reading in symbol tables, it normally does not complain. By setting this variable, GDB produces up to limit complaints about each kind of problem it finds. The default is 0, which creates no complaints. Use a large number to mean "unlimited."

confirm

set confirm

show confirm

GDB normally asks for confirmation before certain operations, such as deleting breakpoints. Set this value to off to disable confirmation. Do this only if you're really sure that you know what you're doing.

convenience

show convenience

Print a list of convenience variables used so far, along with their values. Can be abbreviated show conv.

copying

show copying

Display the GNU General Public License (GPL).

cp-abi

set cp-abi

show cp-abi

The Application Binary Interface (ABI) used for inspecting C++ objects. The default is auto, where GDB determines the ABI on its own. Other acceptable values are gnu-v2 for g++ versions before 3.0, gnu-v3 for g++ versions 3.0 and later, and hpaCC for the HP ANSI C++ compiler.

debug-file-directory

set debug-file-directory dir

show debug-file-directory

Look in dir for separate debugging information files. For use on systems where debugging information is not included in executable files.

demangle-style

set demangle-style style

show demangle-style

Choose the scheme used to convert a "mangled" name back into the original Objective C or C++ name. Available values for style are:

arm | Use the algorithm given in The Annotated C++ Reference Manual (see the Bibliography). The GDB documentation warns that this setting alone does not allow debugging of code produced by cfront.
auto | GDB attempts to figure out the demangling style.
gnu | Use the same scheme as that of the GNU C++ compiler (g++). This is the default.
hp | Use the scheme of HP's ANSI C++ compiler, aCC.
lucid | Use the scheme from Lucid's C++ compiler, lcc.
a In practice this isn't likely to be an issue; cfront-based C++ compilers are no longer common.

directories

show directories

Print the current search path of directories that contain source files.

disassembly-flavor

set disassembly-flavor flavor

show disassembly-flavor

The current instruction set for printing machine-level instructions. This command is currently defined only for the Intel x86 architecture. The flavor is either intel or att; the default is att.

editing

set editing

show editing

Enable editing of command lines as they are typed.

environment

set environment variable[=value]

show environment [variable]

Set environment variable variable to optional value or to the empty string. With no variable, show the entire environment. Otherwise, show the value of the given variable.

exec-done-display

set exec-done-display

show exec-done-display

Enable notification of completion for asynchronous execution commands.

extension-language

set extension-language .ext lang

show extension-language

Associate filename extension .ext with programming language lang.

follow-fork-mode

set follow-fork-mode mode

show follow-fork-mode

Choose which process GDB should continue to debug when the debuggee creates a new process. The value of mode is parent if GDB should follow the parent, or child if GDB should follow the child.

gnutarget

set gnutarget format

show gnutarget

The current file format of the debuggee (core file, executable, .o file). The default is auto, and is probably best left that way.

height

set height count

show height

The number of lines GDB thinks are in a page. Use 0 to keep GDB from pausing.

history

set history feature

show history feature

Control different aspects of GDB's command history. Values and meanings for feature are as follows:

set history expansion, show history expansion

Use csh-style ! commands for history operations. The default is off.

set history filename file, show history filename

Save the command history to file, and restore it from there upon startup. This overrides the default filename, which is taken from the value of the environment variable GDBHISTFILE if it is set. Otherwise, the default filename is ./.gdb_history.

set history save, show history save

Enable saving/restoring of the command history.

set history size amount, show history size

Limit the number of saved history commands to amount.

input-radix

set input-radix base

show input-radix

The default input radix for entering numbers. Acceptable values for base are 8, 10, and 16. The value must be entered unambiguously (leading 0 for octal, leading 0x or 0X for hexadecimal), or in the current input radix.

language

set language lang

show language

Set the source language to lang. Normally, GDB is able to determine the source language from information in the executable file.

listsize

set listsize count

show listsize

The number of source lines GDB lists with the list command.

logging

set logging

set logging option value

show logging

With the usual on and off values, set logging enables and disables logging of GDB command output . With an option and value, the particular logging option is set to value.

Logging Options

file

The file to which GDB logs command output. The default is gdb.txt.

overwrite

If set, overwrite the log file each time. Otherwise GDB appends to it.

redirect

If set, send output to the log file only. The default outputs to both the terminal and the log file.

max-user-call-depth

set max-user-call-depth limit

show max-user-call-depth

Set the maximum number of recursive calls to a user-defined command to limit. When the limit is exceeded, GDB assumes that the command has gone into infinite recursion and aborts with an error.

opaque-type-resolution

set opaque-type-resolution

show opaque-type-resolution

Resolve opaque struct/class/union types when loading symbols. That is, if one file uses a type opaquely (struct foo *), find the definition for that type in the file that defines it.

osabi

set osabi os-abi-type

show osabi

The Operating System/Application Binary Interface of the debuggee. The default is auto, which means GDB figures it out automatically. Use this if you need to override GDB's guess.

output-radix

set output-radix base

show output-radix

The default output radix for displaying numbers. Acceptable values for base are 8, 10, and 16. The value must be entered unambiguously (leading 0 for octal, leading 0x or 0X for hexadecimal), or in the current input radix.

overload-resolution

set overload-resolution

show overload-resolution

When calling an overloaded function from GDB, search for a function whose signature matches the types of the arguments.

pagination

set pagination

show pagination

Enable/disable pagination of output. Default is on.

paths

show paths

Display the current search path for executable programs (the PATH environment variable). This path is also used to find object files.

print

set print print-opt

show print print-opt

GDB lets you control the printing of many different aspects of the debuggee. Many of these options are enabled by typing either set print option-name or set print option-name on. Using off instead of on disables the particular printing option. You can use show print option-name to see if the option's printing setting is on or off. The values for print-opt, and descriptions of GDB's behavior when a particular print-opt is on, are presented in the following list.

set print address, show print address

Include the program counter in stack frame information.

set print array, show print array

Prettyprint arrays. This is easier to read but takes up more space. Default is off.

set print asm-demangle, show print asm-demangle

Demangle C++/Objective C names, even in disassembly listings.

set print demangle, show print demangle

Demangle C++/Objective C names in output.

set print elements count, show print elements

Print no more than count elements from an array. The default is 200; a value of 0 means "unlimited."

set print null-stop, show print null-stop

Stop printing array elements upon encountering one set to zero (ASCII NUL for character arrays, hence the name). Default is off.

set print object, show print object

For a pointer, print the pointed-to object's actual type, which is derived from virtual function table information, instead of the declared type. The default is off, which prints the declared type.

set print pascal_static-members

show print pascal_static-members

Print Pascal static members.

set print pretty, show print pretty

Prettyprint structures, one element per line, with indentation to convey nesting.

set print sevenbit-strings, show print sevenbit-strings

Print 8-bit characters in strings as \nnn.

set print static-members, show print static-members

Print static members when displaying a C++ object.

set print symbol-filename, show print symbol-filename

When printing the symbolic form of an address, include the source filename and line number.

set print union, show print union

Print unions inside structures.

set print vtbl, show print vtbl

Prettyprint C++ virtual function tables. The default is off.

set print max-symbolic-offset max

show print max-symbolic-offset

When displaying addresses, only use the symbol + offset form if the offset is less than max. The default is 0, which means "unlimited."

prompt

set prompt string

show prompt

Set GDB 's prompt to string, or show the prompt string. The default prompt is (gdb).

radix

set radix base

show radix

Set the input and output radixes to the same number. Acceptable values for base are 8, 10, and 16. The value must be entered unambiguously (leading 0 for octal, leading 0x or 0X for hexadecimal), or in the current input radix. See also input-radix and output-radix.

scheduler-locking

set scheduler-locking

show scheduler-locking

On some operating systems, control the scheduling of other threads (those not being traced) in the debuggee. The value is one of on, off, or step. If set to off, all threads run, with the chance that a different thread could pre-empt the debugger (hit a breakpoint, catch a signal, etc.). When set to on, GDB only allows the current thread to run. When set to step, the scheduler locks only during single-stepping operations.

solib-absolute-prefix

set solib-absolute-prefix path

show solib-absolute-prefix

Use path as the prefix for any absolute paths to shared libraries. This is mainly useful for cross-debugging, to find the target's shared libraries when debugging on a host.

solib-search-path

set solib-search-path path

show solib-search-path

Search the colon separated list of directories in path to find a shared library. GDB searches this path after trying solib-absolute-prefix. This too is mainly useful for cross-debugging.

step-mode

set step-mode

show step-mode

Set the mode of the step command. By default, step does not enter functions that lack debugging information. Setting this variable to on causes GDB to enter such functions, allowing you to examine the machine-level instructions.

stop-on-solib-events

set stop-on-solib-events

show stop-on-solib-events

Stop when a shared library event occurs. The most common such events are the loading and unloading of a shared library.

symbol-reloading

set symbol-reloading

show symbol-reloading

On systems that support automatic relinking (such as VxWorks), reload the symbol table when an object file has changed.

trust-readonly-sections

set trust-readonly-sections

show trust-readonly-sections

Believe that read-only sections will remain read-only. This allows GDB to fetch the contents from the object file, instead of from a possibly remote debuggee. This is useful primarily for remote debugging.

tui

set tui feature value

show tui feature

Set the TUI feature feature to value.

TUI Features

set tui active-border-mode mode

show tui active-border-mode

Choose/show the curses library attribute for the border of the active window. Available choices are normal, standout, half, half-standout, bold, and bold-standout.

set tui border-kind kind, show tui border-kind

Set/show the characters used to draw the border to one of the following:

acs

Draw borders using the Alternate Character Set (line drawing characters) if the terminal supports it.

ascii

Draw borders using the regular characters +, -, and |.

space

Draw borders using space characters.

set tui border-mode mode, show tui border-mode

Choose/show the curses library attribute for the border of the other, nonactive windows. Available choices are normal, standout, half, half-standout, bold, and bold-standout.

values

show values [valnum]

show values +

With no arguments, print the last 10 values in the value history (see the earlier section "The Value History"). With valnum, print 10 values centered around that value history item number. With +, print 10 more saved values following the one most recently printed.

variable

set variable assignment

Ensure that assignment actually affects a program variable instead of a GDB variable.

verbose

set verbose

show verbose

Enable display of informative messages during long operations. This reassures you that GDB is still alive.

version

show version

Show the current version of GDB.

warranty

show warranty

Display the "no warranty" provisions from the GNU General Public License (GPL).

watchdog

set watchdog seconds

show watchdog

Wait no more than seconds seconds for a remote target to finish a low-level stepping or continuation operation. If the timeout expires, GDB reports an error.

width

set width numchars

show width

Set the number of characters allowed in a line. Use a value of 0 to keep GDB from wrapping long lines.

write

set write

show write

Allow GDB to write into the executable and core files. The default is off.


17.8. Summary of the info Command

The info command displays information about the state of the debuggee (as opposed to show, which provides information about internal GDB features, variables and options). With no arguments, it provides a list of possible features about which information is available.

info ... | Information displayed
address sym | Information about where symbol sym is stored. This is either a memory address or a register name.
all-registers | Information about all registers, including floating-point registers.
args | Information about the arguments to the current function (stack frame).
break [bpnum] | Information about breakpoint bpnum if given, or about all breakpoints if not.
breakpoints [bpnum] | Same information as the info break command.
catch | Information on exception handlers active in the current frame.
classes [regexp] | Information about Objective-C classes that match regexp, or about all classes if regexp is not given.
display | Information about items in the automatic display list.
extensions | Information about the correspondence of filename extensions to source code programming languages.
f [address] | Same information as the info frame command.
files | Information about the current debugging target, including the current executable, core, and symbol files.
float | Information about the floating-point flags and registers.
frame [address] | With no argument, print information about the current frame. With an address, print information about the frame containing address, but do not make it the current frame.
functions [regexp] | With no argument, print the names and types of all functions. Otherwise, print information about functions whose names match regexp.
handle | The list of all signals and how GDB currently treats them.
line line-spec | The starting and ending address for the code containing the line specified by line-spec. See list for a description of line-spec. This sets the default address to the starting address for the given line, so that x/i may be used to examine instructions.
locals | Information about local variables (static or automatic) accessible from the current frame.
macro macroname | Show the definition and source location for the macro macroname.
mem | Information about memory regions and their attributes.
proc [item] | Information about the running debuggee. Available on systems that supply /proc. The optional item is one of: mappings for available address ranges and how they may be accessed, times for starting time and user and system CPU time, id for process ID information, status for general status of the process, or all for all of the above.
program | Information about the running debuggee, such as running or stopped, and the process ID.
registers [reg ...] | With no arguments, information about all machine registers except floating-point registers. Otherwise, information about the named registers.
s | Same information as the info stack command (which is the same as the backtrace command).
scope address | Information about variables local to the scope containing address, which can be a function name, source line, or absolute address preceded by *.
selectors [regexp] | Information about Objective-C selectors that match regexp, or about all selectors if regexp is not given.
set | Same as the show command with no arguments.
share | Same as the info sharedlibrary command.
sharedlibrary | Information about currently loaded shared libraries.
signal | Same as the info handle command.
source | Information about the source file, such as compilation directory, programming language, and debugging information.
sources | Information about all source files that have debugging information. The output is split into two lists: those whose information has already been read, and those whose information will be read when needed.
stack | Same information as the backtrace command.
symbol address | The name of the symbol (function, variable, etc.) stored at address address.
target | Identical to the info files command.
terminal | Current terminal modes settings.
threads | All the program's current threads.
types [regexp] | Information about types that match regexp, or about all types in the program if regexp is not given.
variables [regexp] | With no argument, print the names and types of all variables except for local variables. Otherwise, print information about variables whose names match regexp.
watchpoints [wpnum] | Information about watchpoint wpnum, or about all watchpoints if wpnum is not given.
win | The names and sizes of all displayed TUI windows.


17.9. Alphabetical Summary of GDB Commands

The following alphabetical summary of GDB commands includes all those that are useful for day-to-day debugging. Esoteric commands, such as those used by GDB's maintainers, or to cross-debug remote systems connected via serial port or a network, have been omitted.

Many of these commands may be abbreviated. The list of abbreviations is provided in the earlier section "Aliases for Other Commands."

add-symbol-file

add-symbol-file file addr [-readnow]

add-symbol-file file [-s section address ...]

Read additional symbol table information from file, which was dynamically loaded into the debuggee outside of GDB's knowledge. You must tell GDB the address at which it was loaded, since GDB cannot determine this on its own. The -readnow option is the same as for the file command; see file for more information. You may use -s to name the memory starting at address with the name section. You can provide multiple section/address pairs with multiple -s options.

advance

advance bp-spec

Continue executing until the program reaches bp-spec, which can have any value acceptable to the break command (see break for the details). This command is like the until command, but it does not skip recursive function calls, and the location doesn't have to be in the current frame.

apropos

apropos regex

Search through the built-in documentation for commands that match the regular expression regex. Multiple words constitute a single regular expression. GDB uses Basic Regular Expressions (see Chapter 7); however, it also ignores case when matching.

attach

attach pid

Attach to the running process pid, and use it to obtain information about in-memory data. You must have appropriate permission in order to attach to a running process.

awatch

awatch expression

Set a watchpoint to stop when expression is either read or written. (Compare rwatch and watch.)

backtrace

backtrace [count]

Print a full list of all stack frames. With a positive count, print only the innermost count stack frames. With a negative count, print only the outermost count stack frames.

Example

Show a backtrace upon hitting a breakpoint:

    ...

    Breakpoint 1, do_print (tree=0x924f9e0) at builtin.c:1573

    1573            struct redirect *rp = NULL;

    (gdb) backtrace

    #0  do_print (tree=0x924f9e0) at builtin.c:1573

    #1  0x08087bef in interpret (tree=0x924f9e0) at eval.c:784

    #2  0x08086b68 in interpret (tree=0x924f980) at eval.c:453

    #3  0x08072804 in main (argc=2, argv=0xbfe41bd4) at main.c:584

break

break [bp-spec]

break bp-specif condition

break bp-spec tHRead threadnum

break bp-spec thread threadnum if condition

Set a breakpoint. The first form sets an unconditional breakpoint; execution of the debuggee stops when the breakpoint is reached. The second form sets a conditional breakpoint: when the breakpoint is reached, GDB evaluates the condition. If the condition is true, execution stops. If it isn't, the program continues. In either case, bp-spec is one of the items given in the following section.

The third and fourth forms are similar to the first and second ones respectively; however, they work on individual threads of control running within the debuggee. They specify that GDB should stop the program only when the given thread threadnum reaches the point specified by bp-spec.

Breakpoint Specifications

The following list shows the different forms that the break command can take.

break

Set a breakpoint at the next instruction in the current stack frame. If you are not in the innermost stack frame, control stops as soon as execution returns to that frame. This is like the finish command, except that finish doesn't leave a breakpoint set. In the innermost frame, GDB stops when the breakpoint is reached. This is most useful inside loop bodies.

break function

Set a breakpoint at the first instruction of function.

break linenumber

Set a breakpoint at line linenumber in the current file.

break file: line

Set a breakpoint at line number line in source file file.

break file: function

Set a breakpoint at function function in source file file.

break + offset break - offset

Set a breakpoint at offset lines forward (+offset) or backward (-offset) from where execution stopped in the current stack frame.

break * address

Set a breakpoint at address. This is useful for parts of the object file that don't have debugging symbols available (such as inside shared libraries).

A breakpoint set at a line or statement stops when the first instruction in that statement is reached.

Example

Set a breakpoint in the main( ) function:

    $ gdb whizprog

    GNU gdb 6.3

    ...

    (gdb) break main

    Breakpoint 1 at 0x80483c0: file whizprog.c, line 6.

call

call expression

Call a function within the debuggee. expression is a function name and parameter list. Non-void results are printed and saved in the value history.

catch

catch event

Place a catchpoint. Execution stops when the specified event occurs.

Catchpoint Events

catch

A C++ exception is caught.

exec

The program calls execve( ). This is not implemented on all systems.

fork

The program calls fork( ). This is not implemented on all systems.

throw

A C++ exception is thrown.

vfork

The program calls vfork( ). This is not implemented on all systems.

cd

cd dir

Change GDB 's working directory to dir.

clear

clear [bp-spec]

Clear a breakpoint. The argument is the same as for the break command (see break).

commands

commands [bp]

... commands ...

end

Supply GDB commands that should run when the program stops at a given breakpoint. With no bp, the list of commands is associated with the most recent breakpoint, watchpoint, or catchpoint that was set, not the one that was most recently executed. To clear a list of commands, supply the commands keyword and follow it immediately with end.

Example

break myfunc if x > 42       Break myfunc if x > 42

    commands                     List of commands

    silent                       Don't print GDB commands

    printf "x = %d\n", x         Print variable value

    cont                         Continue execution

    end                          End of command list

complete

complete prefix

Show possible command completions for prefix. This is intended for Emacs when running GDB in an Emacs buffer.

condition

condition bpcondition bp expression

Add or remove a condition to a given breakpoint. The first syntax removes any condition associated with breakpoint number bp. The second form adds expression as a condition for breakpoint number bp, similar to the break ... if command. See also break.

continue

continue [count]

Resume execution after stopping at a breakpoint. If supplied, count is an ignore count; see the entry for ignore.

Example

Set a breakpoint in main( ). Once there, set another break point and then continue until the new breakpoint is reached.

    (gdb) break main

    Breakpoint 3 at 0x8071d2e: file main.c, line 209.

    (gdb) run ...

    Starting program: ...

    Breakpoint 3, main (argc=2, argv=0xbff59f04) at main.c:209

    209             const char *optlist = "+F:f:v:W;m:D";

    (gdb) break do_print

    Breakpoint 4 at 0x805b239: file builtin.c, line 1573.

    (gdb) continue

    Continuing.

    Breakpoint 4, do_print (tree=0x91589e0) at builtin.c:1573

    1573            struct redirect *rp = NULL;

core-file

core-file [filename]

With no argument, indicate that there is no separate core file. Otherwise, treat filename as the file to use as a core file; that is, a file containing a dump of memory from an executing program.

define

define commandname... commands ...

end

Create a user-defined command named commandname. The series of commands makes up the definition of commandname. Whenever you type commandname, GDB executes the commands. This is similar to functions or procedures in regular programming languages. See also document.

Hooks

If commandname has the form hook-command, where command is a built-in GDB command, when you enter command GDB runs commandname before it runs command.

Similarly, if commandname has the form hookpost-command, then GDB runs the provided sequence of commands after command finishes. You thus have available both pre- and post-execution hook facilities.

Finally, for the purposes of providing hooks, GDB recognizes a pseudo-command named stop that "executes" every time the debuggee stops. This allows you to define a hook of the form hook-stop in order to execute a sequence of commands every time the program stops.

delete

delete [breakpoints] [range ...]

delete display dnums ...

delete mem mnums ...

For the first syntax, remove the given range of breakpoints, watchpoints, or catchpoints. With no arguments, delete all breakpoints. (GDB may prompt for confirmation depending upon the setting of set confirm.) The second syntax removes items from the automatic display list (created with display); see display for more information. The third syntax removes defined memory regions created with mem; see mem for more information.

detach

detach

Detach the debugger from the running process previously attached to with attach.

directory

directory [dirname ...]

Add dirname to the list of directories that GDB searches when attempting to find source files. The directory is added to the front of the search path. With no argument, clear the directory search path.

disable

disable [breakpoints] [range ...]

disable display dnums ...

disable mem mnums ...

With the first syntax, disable the breakpoints in range, or all breakpoints if these are not supplied. GDB remembers disabled breakpoints, but they do not affect execution of the debuggee. The second syntax disables item(s) dnums in the automatic display list; see display for more information. The third syntax disables item(s) mnums in the list of defined memory regions; see mem for more information.

disassemble

disassemble

disassemble pc-valdisassemble start end

Print a range of memory addresses as assembly code instructions. With no argument, print the entire current function. One argument is assumed to be a program counter value; the function containing this value is dumped. Two arguments specify a range of addresses to dump, from (and including) start up to (but not including) end.

display

display

display/format expression

Add expression (usually a variable or address) to the list of values that GDB automatically displays every time the debuggee stops. The format is one of the format letters accepted by the x command; see x for the full list. The trailing "/" and format immediately follow the display command. With no arguments, print the current values of the expressions on the display list.

document

document commandname

... text ...end

Provide documentation for the user-defined command commandname. The documentation consists of the lines provided in text. After executing this command, help commandname displays text. See also define.

dont-repeat

dont-repeat

This command is designed for use inside user-defined commands (see define). It indicates that the user-defined command should not be repeated if the user presses ENTER.

down

down count

Move down count stack frames. Positive values for count move towards more recent stack frames. See also frame and up.

down-silently

down-silently count

Same as the down command, but don't print any messages. This is intended mainly for use in GDB scripts.

echo

echo strings ...

Print strings. You may use the standard C escape sequences to generate nonprinting characters. In particular, you should use \n for newline. Note: unlike the shell-level echo command, GDB 's echo does not automatically supply a newline. You must explicitly request one if you want it.

edit

edit [line-spec]

Edit the lines in the source file as specified by line-spec. See list for values for line-spec. With no argument, edit the file containing the most recently listed line. This uses the value of $EDITOR as the editor, or ex if that environment variable is not set.

else

else

Provide an alternate list of commands to execute if the expression in an if is false. Terminate the commands with end. See if.

enable

enable [breakpoints] [range ...]

enable [breakpoints] delete range ...

enable [breakpoints] once range ...

enable display dnums ...

enable mem mnums ...

The first syntax enables breakpoints; either all breakpoints if no range is supplied, or just the given breakpoints. The second syntax enables the specified breakpoints so that they stop the program when they're encountered, but are then deleted. The third syntax enables the specified breakpoints so that they stop the program when encountered, but then become disabled. The fourth syntax enables items in the automatic display list that were previously disabled with disable; for more information see display. The fifth syntax enables items in the list of defined memory regions; for more information, see mem.

end

end

Terminate a list of commands provided with keywords commands, define, document, else, if, or while.

exec-file

exec-file [filename]

With no argument, discard all information about the executable file. Otherwise, treat filename as the file to execute. This command searches $PATH to find the file if necessary.

fg

fg [count]

An alias for continue; see continue.

file

file

file filename [-readnow]

The first syntax causes GDB to discard all its information on both the symbol file and the executable file. The second syntax treats filename as the file to be debugged; it is used both for symbol table information and as the program to run for the run command.

The -readnow option forces GDB to load symbol table information immediately instead of waiting until information is needed.

finish

finish

Continue execution until the current stack frame (function) is about to return. This is most useful when you accidentally step into a function (using step) that does not have debugging information in it (such as a library function).

focus

focus window

Change the focus to TUI window window. Acceptable values for window are next, prev, src, asm, regs, and cmd.

forward-search

forward-search regex

Search forward from the current line for a line that matches the regular expression regex, and print it.

frame

frame

frame frame-numframe address

Select or print information about the current stack frame (function invocation). Frame zero is the innermost (most recent) stack frame. With no arguments, print the current stack frame. With a frame-num, move to that frame. This is the most common kind of argument. An address argument may be used to select the frame at the given address. This is necessary if the chaining of stack frames has been damaged by a bug. Some architectures may require more than one address.

Example

Move up the call stack toward an older function:

    (gdb) where

    #0  do_print (tree=0x83579e0) at builtin.c:1573

    #1  0x08087bef in interpret (tree=0x83579e0) at eval.c:784

    #2  0x08086b68 in interpret (tree=0x8357980) at eval.c:453

    #3  0x08072804 in main (argc=2, argv=0xbfeb8584) at main.c:584

    (gdb) frame 2

    #2  0x08086b68 in interpret (tree=0x8357980) at eval.c:453

    453                       (void) interpret(tree->rnode);

generate-core-file

generate-core-file [file]

Generate a core file from the state of the debuggee. With file, send the core dump to file. Otherwise, use a file named core.PID.

handle

handle signal keywords ...

Set GDB up to handle one or more signals. The signal may be a signal number, a signal name (with or without the SIG prefix), a range of the form low-high, or the keyword all. The keywords are one or more of the following:

ignore | Ignore the signal; do not let the program see it.
noignore | Same as the pass command.
nopass | Same as the ignore command.
noprint | Do not print a message when the signal arrives.
nostop | Do not stop the program when the signal arrives; let the debuggee receive it immediately.
pass | Pass the signal on through to the program.
print | Print a message when the signal arrives.
stop | Stop the program when the signal arrives. Normally, only "error" signals such as SIGSEGV stop the program.

hbreak

hbreak bp-spec

Set a hardware-assisted breakpoint. The argument is the same as for the break command (see break, earlier in this list). This command is intended for EEPROM/ROM code debugging; it allows you to set a breakpoint at a location without changing the location. However, not all systems have the necessary hardware for this.

help

help [command]

With no arguments, print a list of subtopics for which help is available. With command, provide help on the given GDB command or group of commands.

if

if expression

... commands1 ...[ else

... commands2 ... ]

end

Conditionally execute a series of commands. If expression is true, execute commands1. If an else is present and the expression is false, execute commands2.

ignore

ignore bp count

Set the ignore count on breakpoint, watchpoint, or catchpoint bp to count. GDB does not check conditions as long as the ignore count is positive.

inspect

inspect print-expressions

An obsolete alias for the print command. See print for more information.

info

info [feature]

Display information about feature, which concerns the state of the debuggee. With no arguments, provide a list of features about which information is available. Full details are provided in the section "Summary of the info Command," earlier in this chapter.

jump

jump location

Continue execution at location, which is either a line-spec as for the list command (see list), or a hexadecimal address preceded by a *.

The continue command resumes execution where it stopped, while jump moves to a different place. If the location is not within the current frame, GDB asks for confirmation since GDB will not change the current setup of the machine registers (stack pointer, frame pointer, etc.).

kill

kill

Kill the process running the debuggee. This is most useful to force the production of a core dump for later debugging.

layout

layout layout

Change the layout of the TUI windows to layout. Acceptable values for layout are:

asm | The assembly window only.
next | The next layout.
prev | The previous layout.
regs | The register window only.
split | The source and assembly windows.
src | The source window only.

The command window is always displayed.

list

list functionlist line-spec

List lines of source code, starting at the beginning of function function (first form), or centered around the line defined by line-spec (second form). Pressing the ENTER key repeats the last command; for list, this shows successive lines of source text. A line-spec can take one of the forms shown below.

Line Specifications

list number

List lines centered around line number.

list + offset

list - offset

List lines centered around the line offset lines after (first form) or before (second form) the last line printed.

list file: line

List lines centered around line line in source file file.

list file: function

List lines centered around the opening brace of function function in source file file. This is necessary if there are multiple functions of the same name in different source files.

list * address

List lines centered around the line containing address, which can be an expression.

list first, last

List the lines from first to last, each of which may be any of the previous forms for a line-spec.

list first,

List lines starting with first.

list , last

List lines ending with last.

list +

list -

List the lines just after (first form) or just before (second form) the lines just printed.

macro

macro expand expressionmacro expand-once expressionmacro define macro bodymacro define macro(args) bodymacro undefine macro

Work with C preprocessor macros. As of GDB 6.3, not all of these are implemented.

macro expand expression

Display the result of macro expanding expression. The results are not evaluated, thus they don't need to be syntactically valid. expand may be abbreviated exp.

macro expand-once expression

Expand only those macros whose names appear in expression instead of fully expanding all macros. expand-once may be abbreviated exp1. Not implemented as of GDB 6.3.

macro define macro body

macro define macro(args) body

Define a macro named macro with replacement text body. As in C and C++, the first form defines a symbolic constant, while the second form defines a macro that accepts arguments. Not implemented as of GDB 6.3.

macro undefine macro

Remove the definition of the macro named macro. This works only for macros defined with macro define; you cannot undefine a macro in the debuggee. Not implemented as of GDB 6.3.

make

make [args]

Run the make program, passing it args. Equivalent to the shell make args command. This is useful for rebuilding your program while remaining within GDB.

mem

mem start-addr end-addr attributes ...

Define a memory region, i.e., a portion of the address space starting at start-addr and ending at end-addr that has particular attributes.

Memory Access Attributes

ro | Memory is read-only.
rw | Memory is read-write.
wo | Memory is write-only.
8, 16, 32, 64 | GDB should use memory accesses of the specified width in bits. This is often needed for memory-mapped device registers.

next

next [count]

Run the next statement. Unlike step, a function call is treated as a simple statement; single-stepping does not continue inside the called function. With a count, run the next count statements. In any case, execution stops upon reaching a breakpoint or receipt of a signal. See also step.

nexti

nexti [count]

Run the next machine instruction. Otherwise, this is similar to the next command in that single-stepping continues past a called function instead of into it.

nosharedlibrary

nosharedlibrary

Unload all shared libraries from the debuggee.

output

output expressionoutput/format expression

Print expression, completely unadorned. No newlines are added, nor is the value preceded by the usual $n =. Neither is the value added to the value history. With "/" and format, output the expression using format, which is the same as for the print command; see print.

path

path dir

Add directory dir to the front of the PATH environment variable.

print

print [/format] [expression]

Print the value of expression. If the first argument is "/" and format, use the format to print the expression. Omitting expression prints the previous expression, allowing you to use a different format to see the same value. The allowed format values are a subset of the format items for the x command; see also x, later in this section.

Print Formats

a | Print the value as an address. The address is printed as both an absolute (hexadecimal) address, and as an offset from the nearest symbol.
c | Print the value as a character constant.
d | Print the value as a signed decimal integer.
f | Print the value as a floating point number.
o | Print the value as an octal integer.
t | Print the value as a binary integer (t stands for "two").
u | Print the value as an unsigned decimal integer.
x | Print the value as a hexadecimal integer.

Example

Print a wide character value as a regular character:

    (gdb) print tmp->sub.val.wsp

    $2 = (wchar_t *) 0x99f0910

    (gdb) print/c *$2

    $3 = 97 'a'

print-object

print-object object

Cause the Objective C object object to print information about itself. This command may only work with Objective C libraries that define the hook function _NSPrintForDebugger( ).

printf

printf format-string, expressions ...

Print expressions under control of the format-string, as for the C library printf(3) function. GDB allows only the simple, single-letter escape sequences (such as \t and \n) to appear in format-string.

ptype

ptype

ptype expressionptype type-name

Print the full definition of a type. This differs from whatis, in that whatis only prints type names, while ptype gives a full description.

With no argument (the first syntax), print the type of the last value in the value history. This is equivalent to ptype $. With expression (the second syntax), print the type of expression. Note that the expression is not evaluated. No operators with side effects (such as ++, or a function call) execute. The third syntax prints the type of type-name, which is either the name of a type or one of the keywords class, enum, struct, or union, followed by a tag. See also whatis.

pwd

pwd

Print GDB 's current working directory.

quit

quit

Exit GDB.

rbreak

rbreak regexp

Set breakpoints on all functions matching the regular expression regexp. The regular expression syntax used is that of grep (i.e., Basic Regular Expressions, see Chapter 7). This is useful for overloaded functions in C++.

refresh

refresh

Redraw and refresh the screen for the TUI. See the earlier section "The GDB Text User Interface" for more information.

return

return [expression]

Cause the current stack frame to return to its caller. If provided, expression is used at the return value. GDB pops the current stack frame and any below it (functions it called) from the execution stack, causing the returning frame's caller to become the current frame. Execution does not resume; the program remains stopped until you issue a continue command.

reverse-search

reverse-search regex

Search backwards from the current line for a line that matches the regular expression regex, and print it.

run

run [arguments]

Run the debuggee, optionally passing it arguments as the command-line arguments. GDB also supports simple I/O redirections (<, >, >>); pipes are not supported. GDB remembers the last-used arguments; thus a plain run command restarts the program with these same arguments. (Use set args to clear or change the argument list.)

The debuggee receives the arguments you give to the run command, the environment as inherited by GDB and modified by set environment, the current working directory, and the current standard input, standard output, and standard error (unless redirected).

rwatch

rwatch expression

Set a watchpoint to stop when expression is read. (Compare awatch and watch.)

search

search regex

An alias for forward-search. See forward-search for more information.

section

section sectname address

Change the base address of sectname to address. This is a last-ditch command, used when the executable file format doesn't contain data on section addresses or if the data in the file is wrong.

select-frame

select-frame

select-frame frame-numselect-frame address

Same as the frame command, except that it does not print any messages. See frame for more information.

set

set [variable]

Change the setting either of GDB variables or variables in the debuggee. See the earlier section "Summary of set and show Commands" for more information.

sharedlibrary

sharedlibrary [regexp]

With no argument, load all the shared libraries required by the program or core file. Otherwise, load only those files whose names match regexp.

shell

shell [command args]

Run the shell command command with arguments args without leaving GDB. With no arguments, start an interactive subshell.

Example

Run grep to find the definition of a macro:

    510             return tmp_number((AWKNUM) len);

    (gdb) shell grep tmp_number *.h

    whizprog.h:#define   tmp_number(x)   mk_number((x), TEMP)

    (gdb)

show

show [variable]

Show the setting of internal GDB variables. See the earlier section "Summary of set and show Commands" for more information.

signal

signal sig

Continue the program running, and immediately send it signal sig. sig may be either a signal number or a signal name. The signal number 0 is special: if the program stops due to receipt of a signal, sending signal 0 resumes it without delivering the original signal.

silent

silent

Don't print breakpoint-reached messages. Use this command inside a commands list; see commands.

source

source file

Read and execute the commands in file. The commands are not printed as they are read, and an error in any one command terminates execution of the file. When executing a command file, commands that normally ask for confirmation do not do so, and many commands that would otherwise print messages are silent.

step

step [count]

Run the next statement. This differs from the next command in that if the next statement is a function call, step steps into it and continues single-stepping in the called function. However, next calls the function without stepping into it. With a count, step through count statements. In any case, execution stops upon reaching a breakpoint or receipt of a signal. See also next.

stepi

stepi [count]

Run the next machine instruction. Otherwise, this is similar to the step command in that single-stepping continues into a called function. With a count, step through count instructions.

symbol-file

symbol-file

symbol-file filename [-readnow]

With no argument, discard all symbol table information. Otherwise, treat filename as the file to get symbol table information from, and as the file to execute. This command searches $PATH to find the file if necessary. The -readnow option has the same meaning as for the file command; see file for more information.

tbreak

tbreak bp-spec

Set a temporary breakpoint. The argument is the same as for the break command (see break, earlier in this list). The difference is that once the breakpoint is reached, it is removed.

tcatch

tcatch event

Set a temporary catchpoint. The argument is the same as for the catch command (see catch, earlier in this list). The difference is that once the catchpoint is reached, it is removed.

thbreak

thbreak bp-spec

Set a temporary hardware-assisted breakpoint. The argument is the same as for the hbreak command (see hbreak, earlier in this list).

thread

thread threadnumtHRead apply [threadnum | all] command

The first form makes threadnum the current thread, i.e., the one that GDB works with. The second form lets you apply command to either the specific thread threadnum or to all threads.

tty

tty device

Set the debuggee's input and output to device (typically the device file for a terminal).

tui

tui reg regkind

For the TUI, update the register window to display the register set regkind.

Register Sets

The following are the acceptable values for regkind.

float | The floating-point registers.
general | The general purpose registers.
next | The "next" register group. Predefined register groups are all, float, general, restore, save, system, and vector.
system | The system registers.

undisplay

undisplay dnums ...

Remove display items dnums from the automatic display list. See display for more information.

unset

unset environment variable

Remove environment variable variable from the environment passed to the debuggee.

until

until [location]

Continue execution until it reaches the next source line after the current line. This is most useful for reaching the line after the end of a loop body. Without a location, until uses single-stepping to reach the next source line. With a location, it uses an internal breakpoint to reach the next source line; this is much faster. The location may be any form acceptable to the break command; see break for more information.

Example

Use until to skip through the entire execution of a loop:

    $ nl -ba foo.c                 Show source file

         1  #include <stdio.h>

         2

         3  int main(void)

         4  {

         5      int i;

         6

         7      for (i = 1; i <= 10; i++)

         8              printf("i = %d\n", i);

         9

        10      printf("all done: i = %d\n", i);

        11  }

    $ gcc -g foo.c -o foo          Compile it

    $ gdb foo                      Run GDB

    GNU gdb 6.3

    ...

    (gdb) break main               Set breakpoint

    Breakpoint 1 at 0x8048358: file foo.c, line 7.

    (gdb) run                      Start it running

    Starting program: /tmp/foo

    Breakpoint 1, main (  ) at foo.c:7

    7       for (i = 1; i <= 10; i++)

    (gdb) next                     Next statement

    8           printf("i = %d\n", i);

    (gdb)                         ENTER repeats 'next'

    i = 1

    7       for (i = 1; i <= 10; i++)

    (gdb)                         Same

    8           printf("i = %d\n", i);

    (gdb)                         Same

    i = 2

    7       for (i = 1; i <= 10; i++)

    (gdb) until 9                  Finish up the loop

    i = 3

    i = 4

    i = 5

    i = 6

    i = 7

    i = 8

    i = 9

    i = 10

    main (  ) at foo.c:10

    10      printf("all done: i = %d\n", i);

    (gdb) continue                  Finish program

    Continuing.

    all done: i = 11

    Program exited with code 021.

    (gdb) quit

up

up count

Move up count stack frames. Positive values for count move towards less recent stack frames. See also frame and down.

up-silently

up-silently count

Same as the up command, but don't print any messages. Intended mainly for use in GDB scripts.

update

update

For the TUI, update the source window and the current execution point.

watch

watch expression

Set a watchpoint to stop when expression is written. (Compare awatch and rwatch.)

whatis

whatis [expression]

With no argument, print the type of the last value in the value history. This is equivalent to whatis $. With expression, print the type of expression. Note that the expression is not evaluated. No operators with side effects (such as ++, or a function call) execute. See also ptype.

where

where [count]

Identical to the backtrace command; see backtrace for more information.

while

while expression... commands ...

end

Repeatedly execute a series of commands. As long as expression is true, execute commands.

winheight

winheight win ±amount

For the TUI, change the height of window win by amount. Using + increases the height; using - decreases it. The window name win may be one of asm, cmd, regs, or src.

x

x [[/NFU] addr]

Examine the data at address. Subsequent x commands without an address move forward in memory according to the values for N, F, and U.

The N value is a repeat count, for example, to examine a given number of instructions. The F value is a format, indicating how to print the data. The U value is the unit size in bytes of the items to be displayed.

GDB stores the address printed by the x command in the $_ convenience variable. It stores the contents of the address in the $_ _ convenience variable.

Format Values

a | Print the value as an address. The address is printed as both an absolute (hexadecimal) address and as an offset from the nearest symbol.
c | Print the value as a character constant.
d | Print the value as a signed decimal integer.
f | Print the value as a floating point number.
i | Print the value as a machine instruction.
o | Print the value as an octal integer.
s | Print the value as a NUL-terminated string.
t | Print the value as a binary integer (t stands for "two").
u | Print the value as an unsigned decimal integer.
x | Print the value as a hexadecimal integer.

Unit Size Values

b | Bytes.
g | Giant words, i.e., 8 bytes.
h | Halfwords, i.e., 2 bytes.
w | Words, i.e., 4 bytes.


Chapter 18. Writing Manual Pages

The man command prints the online "manual page" for commands, system calls, functions, devices and file formats. Developers creating new software also need to create manual pages for their programs. This in turn requires a basic understanding of the Unix troff text-processing program and the man macro package.

This chapter presents the following topics:

  • Introduction

  • Overview of nroff/troff

  • Alphabetical summary of the man macros

  • Predefined strings

  • Names used internally by the man macros

  • Sample document


18.1. Introduction

The standard Unix text-processing tools are nroff and troff. They are not What You See Is What You Get (WYSIWYG) word-processors. Rather, they are text processing programs, where the input consists of a mixture of text to be formatted and special commands that instruct the programs how to format the text.

troff is for output devices such as typesetters and high resolution laser printers that can handle variable-width fonts and different character sizes. nroff is for simpler devices where all characters have the same width, such as terminals or line printers. Both programs accept the same set of commands; thus, carefully prepared input may be used with both programs to produce reasonable results. The original troff program worked for only one specific typesetter. The modern version, known as "device independent troff," or ditroff, can be tuned via specific drivers to work on multiple output devices.

Different commercial versions of Unix come with different versions of the troff suite. GNU/Linux and BSD systems all use GNU troff (groff), which is an excellent, full-featured implementation of ditroff and all the troff preprocessors. The Internet starting point for groff is http://www.gnu.org/software/groff/groff.html. We recommend downloading and building it if you intend to do serious troff-based typesetting work.[*]

[*] groff is written in C++, so you may need a C++ compiler. In this case, you may first need to bootstrap g++, the GNU C++ compiler from GCC (the GNU Compiler Collection).

Knowledge of nroff and troff was once an integral part of a Unix wizard's claims to Unix mastery. Over time though, they have been superseded for daily document preparation, either by WYSIWYG programs, or by TEX and LATEX. More information about troff in general is available from http://www.troff.org/.

However, one important task where knowledge of troff is still handy is the writing of manual pages (for the man command) to accompany software. This chapter introduces the subset of the troff command and feature set that is useful for writing manual pages, and then describes the man macros, concluding with a sample manual page. See also the Writing Manual Pages appendix in Classic Shell Scripting, cited in the Bibliography.

The canonical reference for nroff/troff is Bell Labs Computing Science Technical Report #54, Troff User's Manual, by J.F. Ossanna and B.W. Kernighan. It is available in PostScript from http://cm.bell-labs.com/cm/cs/cstr/54.ps.gz. You should read it if you plan to do any serious work in nroff/troff (such as writing or modifying macro packages). This document explains the ideas of diversions, environments, fields, registers, strings, and traps. The online Info documentation for groff explains the GNU-specific extensions that it supplies.


18.2. Overview of nroff/troff

This section is condensed from the material on troff from the third edition of this book. It covers features available in all versions of nroff and troff, and focuses on those features necessary for writing manual pages.

18.2.1. Command-Line Invocation

nroff and troff are invoked from the command line as follows:

    nroff  [options]  [files]

    troff  [options]  [files]

Although both formatters support a plethora of options, the following two are the most important for everyday use.

-m name

Prepend a macro file to input files. Historically, one of /usr/lib/tmac/tmac.name or /usr/share/lib/tmac/tmac.name were the locations of the macros for name. Solaris uses /usr/share/lib/tmac/name. GNU troff uses something like /usr/local/share/groff/x.y.z/tmac/name.tmac. The actual location and filename(s) vary among different Unix systems.

-T name

Prepare output designed for printer or typesetter name. For device names, see your specific documentation or a local expert. GNU troff provides both PostScript and TEX DVI output.

18.2.1.1. Example

Format a manual page for printing using groff:

    $ groff -man /usr/share/man/man1/awk.1 | lpr

18.2.2. Conceptual Overview

This section provides a brief overview of how to prepare input for nroff and troff. It presents the following topics:

  • Requests and macros

  • Common requests

  • Specifying measurements

  • Requests that cause a line break

  • Embedded formatting controls

18.2.2.1. Requests and macros

Formatting is specified by embedding brief codes (called requests) into the text source file. These codes act as directives to nroff and troff when they run. For example, to center a line of text, type the following code in a file:

    .ce

    This text should be centered.

When formatted, the output appears centered:

                    This text should be centered.

There are two types of formatting codes:

  • Requests, which provide the most elementary instructions

  • Macros, which are predefined combinations of requests

Requests, also known as primitives, allow direct control of almost any feature of page layout and formatting. Macros combine requests to create a total effect. In a sense, requests are like statements, and macros are like functions.

All nroff/troff requests are two-letter lowercase names. Macros are usually upper- or mixed-case names. GNU troff removes the two-character restriction on the length of names.

18.2.2.2. Specifying measurements

With some requests, the numeric argument can be followed by a scale indicator that specifies a unit of measurement. The valid indicators and their meanings are listed in the following table. Note that all measurements are internally converted to basic units (this conversion is shown in the last column). A basic unit is the smallest possible size on the printer device. The device resolution (e.g., 600 dots per inch) determines the size of a basic unit. Also, T specifies the current point size, and R specifies the device resolution.

Scale indicator | Meaning | Equivalent unit | # of basic units
c | Centimeter | 0.394 inches | R / 2.54
i | Inch | 6 picas or 72 points | R
m | Em | T points | R x T / 72
n | En | 0.5 em | R x T / 144
p | Point | 1/72 inch | R / 72
P | Pica | 1/6 inch | R / 6
u | Basic unit |  | 1
v | Vertical line space |  | (Current value of line spacing in basic units)
None | Default |  |

It is worth noting that all numbers in nroff/troff are stored internally using integers. This applies even to apparently fractional values in commands such as:

    .sp .5

which spaces down one-half of the current vertical spacing.

An "em" is the width of the letter "m" in the current font and point size. An "en" is the width of the letter "n" in the current font and point size. Note that in nroff, an "em" and an "en" are the same—the width of one character.

18.2.2.3. Requests that cause a line break

A line break occurs when nroff/troff writes the current output line, even if it is not completely filled. Most requests can be interspersed with text without causing a line break in the output. The following requests cause a break:

    .bp   .ce   .fi   .in   .sp

    .br   .cf   .fl   .nf   .ti

If you need to prevent these requests from causing a break, begin them with the "no break" control character (normally ') instead of a dot (.). For example, .bp flushes the current output line and starts a new page immediately. However, 'bp starts a new page, with the current output line not being written until it is full.

18.2.2.4. Embedded formatting controls

In addition to requests and macros, which are written on their own separate lines, you may also have formatting controls embedded within your text lines. These typically provide the following capabilities:

General formatting

Considerable formatting control is available, such as switching fonts (\f), changing point sizes (\s), computing widths (\w), and many other things. For example:

    This text is in \fIitalic\fR, but this is in roman.

    This text is \s-2VERY SMALL\s0 but this text is not.

Special characters

Predefined special typesetting characters, such as the bullet symbol \(bu (·), the left hand \(lh ( [image] ), and the right hand \(rh ( [image] ).

Strings

User-defined sequences of characters, like macros, but usable inline. For example:

    .\" define a shorthand for UNIX

    .ds UX  the \s-1UNIX\s0 Operating System

    ...

    Welcome to \*(UX.

    While \*(UX may appear daunting at first,

    it is immensely powerful. ...

Number registers

Like variables in programming languages, number registers store numeric values that can be printed in a range of formats (decimal, roman, etc.). Number registers hold integer values; fractional values are converted into the corresponding number of basic units. Number registers can be set to auto-increment or auto-decrement, and are particularly useful when writing macro packages, for managing automatic numbering of headings, footnotes, figures, and so on. For example:

    .nr Cl 0 1  \" Chapter Level

    .de CH

    .bp

    \\n+(Cl. \\$1 \\$2 \\$3

    ..

This creates a macro that uses register Cl as the "chapter level." The first three arguments to the macro (represented in the macro body by \\$1 etc.) become the chapter title. The extra backslashes are needed inside the macro definition to prevent too-early evaluation.

Comments in nroff/troff begin with \". Lines beginning with . that contain an unknown request are ignored. In general, don't put leading whitespace on your text lines. This causes a break, and nroff and troff honor the leading whitespace literally.

18.2.3. Outline of Useful Requests

The following is a list of the requests that you may see in manual pages, or that were mentioned earlier in the chapter.

.ad | Adjust margins. | .ls | Line spacing (e.g., single-spaced).
.bp | Begin a new page. | .na | Don't adjust margins.
.br | Break the output line. | .ne | Keep lines on same page if there's room.
.ce | Center lines. | .nf | Don't fill lines.
.cf | Copy raw file to output. | .nr | Define a number register.
.de | Define a macro. | .po | Change page offset.
.ds | Define a string. | .ps | Set point size.
.fi | Fill lines. | .so | Go to a file, then return.
.fl | Flush output buffer. | .sp | Output blank spacing.
.ft | Set font. | .ta | Define tab settings.
.in | Indent. | .ti | Indent next line (temporary indent).
.ll | Set line length. | .vs | Set vertical spacing for lines.

18.2.4. Useful Escape Sequences

This partial list of troff escape sequences provides those that are most useful.

Sequence | Effect
\\ | Prevent or delay the interpretation of \.
\e | Printable version of the current escape character (usually \).
\- | - (minus sign in the current font).
\. | Period (dot).
\space | Unpaddable space-size space character.
\newline | Concealed (ignored) newline.
\| | 1/6-em narrow space character (zero width in nroff).
\^ | 1/12-em half-narrow space character (zero width in nroff).
\& | Nonprinting, zero-width character.
\" | Beginning of comment.
\$n | Interpolate macro argument 1 [image] n [image] 9.
\(xx | Character named xx. See the following section "Special Characters."
\*x or \*(xx | Interpolate string x or xx.
\fx or \f(xx or \fn | Change to font named x or xx or to position n. If x is P, return to the previous font.
\nx, \n(xx | Interpolate number register x or xx.
\n+x, \n+(xx | Interpolate number register x or xx, applying auto-increment.
\n-x, \n-(xx | Interpolate number register x or xx, applying auto-decrement.
\sn, \s±n | Change point size to n or increment by n. For example, \s0 returns to previous point size.
\s(nn, \s±(nn | Just like \s, but allow unambiguous two-character point sizes (ditroff only).
\w'string' | Interpolate width of string in basic units.

18.2.5. Special Characters

Table 18-1 lists the special characters that reside in the standard fonts. troff includes a large number of other characters that we have not described here, since they are mostly for typesetting mathematics.

Table 18-1. Characters in the standard fonts

Input

Char

Character name

'

'

Close quote

'

'

Open quote

\(em

—

Em-dash (width of "m")

\(en

–

En-dash (width of "n")

\-

-

Minus in current font

-

-

Hyphen

\(hy

-

Hyphen

\(bu

·

Bullet

\(sq

Square

\(rg

®

Registered

\(co

©

Copyright


18.3. Alphabetical Summary of man Macros

Brian Kernighan describes the reason for macro packages very pithily:

Since bare troff is unusable by humans, a race of gods now gone created macro packages for mortals to use.

Today, the man macros are the most widely used macro package. They are used for writing program manual pages for the online manual, accessed via the man command.

As many as six arguments may be given for all the macros that change fonts or produce a heading. The seventh and later arguments are ignored. Use double quotes around multiple words to get longer headings.

The .TS, .TE, .EQ, and .EN macros are not defined by the man macros. Because nroff and troff ignore unknown requests, you can still use them in your manpages; tbl and eqn work with no problems.

.B

.B [text ...]

Set the arguments in the bold font, with a space between each argument. If no arguments are supplied, the next input line is set in bold.

.BI

.BI barg iarg ...

Set alternating barg in bold and iarg in italic, with no intervening spaces.

.BR

.BR barg rarg ...

Set alternating barg in bold and rarg in roman, with no intervening spaces.

.DT

.DT

Reset the tab stops to their defaults, every 1/2 inch.

.HP

.HP [indent]

tag text

Start a paragraph with a "hanging" indent, one where a tag sits out to the left side. The optional indent is how far to indent the paragraph. The tag text follows on the next line. See the example under .TP.

.I

.I [text ...]

Set the arguments in the italic font, with a space between each argument. If no arguments are supplied, the next input line is set in italic.

.IB

.IB iarg barg ...

Set alternating iarg in italic and barg in bold, with no intervening spaces.

.IP

.IP tag [indent]

Start a paragraph with a hanging indent, one where a tag sits out to the left side. Unlike .HP and .TP, the tag is supplied as an argument to the macro. The optional indent is how far to indent the paragraph.

Example

.IP 1.

    The first point is ...

    .IP 2.

    The second point is ...

.IR

.IR iarg rarg ...

Set alternating iarg in italic and rarg in roman, with no intervening spaces.

.LP

.LP

Start a new paragraph. Just like .PP.

.P

.P

Start a new paragraph. Just like .PP.

.PD

.PD [distance]

Set the interparagraph spacing to distance. With no argument, reset it to the default. Most useful to get multiple tags for a paragraph.

Example

Show that two options do the same thing:

    .PP

    .I Whizprog

    accepts the following options.

    .TP \w'\fB\-\^\-help\fP'u+3n

    .PD 0

    .B \-h

    .TP

    .PD

    .B \-\^\-help

    Print a helpful message and exit.

.PP

.PP

Start a new paragraph. This macro resets all the defaults, such as point size, font, and spacing.

.RB

.RB rarg barg ...

Set alternating rarg in roman and barg in bold, with no intervening spaces.

.RE

.RE

End a relative indent. Each .RE should match a preceding .RS. See .RS for an example.

.RI

.RI rarg iarg ...

Set alternating rarg in roman and iarg in italic, with no intervening spaces.

.RS

.RS [indent]

Start a relative indent. Each successive .RS increases the indent. The optional indent is how far to indent the following text. Each .RS should have an accompanying .RE.

Example

.PP

    There are a number of important points to remember.

    .RS

    .IP 1.

    The first point is ...

    .IP 2.

    The second point is ...

    ...

    .RE

    Forget these at your own risk!

.SB

.SB arg ...

Set arguments in bold, using a smaller point size, separated by spaces.

.SH

.SH arg ...

Section header. Start a new section, such as NAME or SYNOPSIS. Use double quotes around multiple words for longer headings.

.SM

.SM arg ...

Set arguments in roman, using a smaller point size, separated by spaces.

.SS

.SS arg ...

Subsection header. Start a new subsection. Use double quotes around multiple words for longer headings.

.TH

.TH title section date ...

Title heading. This is the first macro of a manpage, and sets the header and footer lines. The title is the name of the manpage. The section is the section the manpage should be in (a number, possibly followed by a letter). The date is the date the manpage was last updated. Different systems have different conventions for the remaining arguments to this macro. For Solaris, the fourth and fifth arguments are the left-page footer and the main (center) header.

Example

.TH WHIZPROG 1L "April 1, 2007"

    .SH NAME

    whizprog \- do amazing things

    ...

.TP

.TP [indent]

tag text

Start a paragraph with a hanging indent, one where a tag sits out to the left side. The optional indent is how far to indent the paragraph. The tag text follows on the next line. See also the example under .PD.

Example

.TP .2i

    1.

    The first point is ...

    .TP .2i

    2.

    The second point is ...


18.4. Predefined Strings

The following strings are predefined by the man macros; of these, only R and S are documented.

String | Effect in troff | Effect in nroff
\*(lq | '' ('') | "
\*(rq | '' ('') | "
\*R | \(rg (®) | (Reg.)
\*S | Restore default point size | Restore default point size


18.5. Internal Names

The Solaris man macros use a number of macro, string, and number register names that begin with ], }, and ). Such names should be avoided in your own files.

The number registers D, IN, LL, P, X, d, m, and x are used internally by the Solaris man macros. Using .nr D 1 before calling the .TH macro generates pages with different even and odd footers.[*]

[*] This information was gleaned by examining the actual macros. It is not documented, so Your Mileage May Vary.


18.6. Sample Document

The output of this sample document is shown in Figure 18-1.

    .TH WHIZPROG 1 "April 1, 2007"

    .SH NAME

    whizprog \- do amazing things

    .SH SYNOPSIS

    .B whizprog

    [

    .I options

    ] [

    .I files

    \&... ]

    .SH DESCRIPTION

    .I Whizprog

    is the next generation of really

    .B cool

    do-it-all programs. ...

    .SH OPTIONS

    .PP

    .I Whizprog

    accepts the following options.

    .TP \w'\fB\-\^\-level\fP'u+3n

    .PD 0

    .B \-h

    .TP

    .PD

    .B \-\^\-help

    Print a helpful message and exit.

    .TP

    .BI \-\^\-level " level"

    Set the level for the

    .B \-\^\-stun

    option.

    .TP

    .B \-\^\-stun

    Stun the competition, or other beings, as needed. ...

    .SH SEE ALSO

    .IR "Whizprog \- The Be All and End All Program" ,

    by J. Programmer.

    .PP

    .IR wimpprog (1)

    .SH FILES

    .B /dev/phaser

    .br

    .B /dev/telepath

    .SH CAVEATS

    .PP

    There are a number of important points to remember.

    .RS

    .IP 1.

    Use

    .B \-\^\-help

    to get help.

    .IP 2.

    Use

    .B \-\^\-stun

    with care.  ...

    .RE

    Forget these at your own risk!

    .SH BUGS

    The

    .B \-\^\-stun

    option currently always uses

    .BR "\-\^\-level 10" ,

    making it rather dangerous.

    .SH AUTHOR

    J. Programmer,

    .B jp@wizard-corp.com

Figure 18-1. Output of sample document

    Previous Section < Day Day Up > Next Section


Appendix A. ISO 8859-1 (Latin-1) Character Set

This appendix presents the set of ISO 8859-1 (Latin-1) characters, along with their equivalent values in decimal, octal, and hexadecimal. This character set suffices for English and languages that can be written using just the English alphabet, plus the major Western European languages. The lower half of this set of characters is identical to traditional ASCII . Table A-1 shows nonprinting characters; it's useful when you need to represent nonprinting characters in some printed form, such as octal. For example, the echo and tr commands let you specify characters using octal values of the form \nnn. Also, the od command can display nonprinting characters in a variety of forms.

Table A-2 shows printing characters. This table is useful when using the previous commands, but also when specifying a range of characters in a pattern-matching construct. The characters from decimal 128–159 are not used in Latin-1.

Table A-1. Nonprinting characters

Decimal

Octal

Hex

Character

Remark

0

000

00

CTRL-@

NUL (Null prompt)

1

001

01

CTRL-A

SOH (Start of heading)

2

002

02

CTRL-B

STX (Start of text)

3

003

03

CTRL-C

ETX (End of text)

4

004

04

CTRL-D

EOT (End of transmission)

5

005

05

CTRL-E

ENQ (Enquiry)

6

006

06

CTRL-F

ACK (Acknowledge)

7

007

07

CTRL-G

BEL (Bell)

8

010

08

CTRL-H

BS (Backspace)

9

011

09

CTRL-I

HT (Horizontal tab)

10

012

0A

CTRL-J

LF (Linefeed)

11

013

0B

CTRL-K

VT (Vertical tab)

12

014

0C

CTRL-L

FF (Formfeed)

13

015

0D

CTRL-M

CR (Carriage return)

14

016

0E

CTRL-N

SO (Shift out)

15

017

0F

CTRL-O

SI (Shift in)

16

020

10

CTRL-P

DLE (Data link escape)

17

021

11

CTRL-Q

DC1 (XON)

18

022

12

CTRL-R

DC2

19

023

13

CTRL-S

DC3 (XOFF)

20

024

14

CTRL-T

DC4

21

025

15

CTRL-U

NAK (Negative acknowledge)

22

026

16

CTRL-V

SYN (Synchronous idle)

23

027

17

CTRL-W

ETB (End transmission blocks)

24

030

18

CTRL-X

CAN (Cancel)

25

031

19

CTRL-Y

EM (End of medium)

26

032

1A

CTRL-Z

SUB (Substitute)

27

033

1B

CTRL-[

ESC (Escape)

28

034

1C

CTRL-\

FS (File separator)

29

035

1D

CTRL-]

GS (Group separator)

30

036

1E

CTRL-^

RS (Record separator)

31

037

1F

CTRL-_

US (Unit separator)

127

177

7F

DEL (Delete or rubout)

Table A-2. Printing characters

Decimal

Octal

Hex

Character

Remark

32

040

20

Space

33

041

21

!

Exclamation point

34

042

22

"

Double quote

35

043

23

#

Number sign

36

044

24

$

Dollar sign

37

045

25

%

Percent sign

38

046

26

&

Ampersand

39

047

27

'

Apostrophe

40

050

28

(

Left parenthesis

41

051

29

)

Right parenthesis

42

052

2A

*

Asterisk

43

053

2B

+

Plus sign

44

054

2C

,

Comma

45

055

2D

-

Hyphen

46

056

2E

.

Period

47

057

2F

/

Slash

48

060

30

0

49

061

31

1

50

062

32

2

51

063

33

3

52

064

34

4

53

065

35

5

54

066

36

6

55

067

37

7

56

070

38

8

57

071

39

9

58

072

3A

:

Colon

59

073

3B

;

Semicolon

60

074

3C

<

Left angle bracket

61

075

3D

=

Equal sign

62

076

3E

>

Right angle bracket

63

077

3F

?

Question mark

64

100

40

@

At sign

65

101

41

A

66

102

42

B

67

103

43

C

68

104

44

D

69

105

45

E

70

106

46

F

71

107

47

G

72

110

48

H

73

111

49

I

74

112

4A

J

75

113

4B

K

76

114

4C

L

77

115

4D

M

78

116

4E

N

79

117

4F

O

80

120

50

P

81

121

51

Q

82

122

52

R

83

123

53

S

84

124

54

T

85

125

55

U

86

126

56

V

87

127

57

W

88

130

58

X

89

131

59

Y

90

132

5A

Z

91

133

5B

[

Left square bracket

92

134

5C

\

Backslash

93

135

5D

]

Right square bracket

94

136

5E

^

Caret

95

137

5F

_

Underscore

96

140

60

'

Back quote

97

141

61

a

98

142

62

b

99

143

63

c

100

144

64

d

101

145

65

e

102

146

66

f

103

147

67

g

104

150

68

h

105

151

69

i

106

152

6A

j

107

153

6B

k

108

154

6C

l

109

155

6D

m

110

156

6E

n

111

157

6F

o

112

160

70

p

113

161

71

q

114

162

72

r

115

163

73

s

116

164

74

t

117

165

75

u

118

166

76

v

119

167

77

w

120

170

78

x

121

171

79

y

122

172

7A

z

123

173

7B

{

Left curly brace

124

174

7C

|

Vertical bar

125

175

7D

}

Right curly brace

126

176

7E

~

Tilde

160

240

A0

Non-breaking space

161

241

A1

¡

Inverted exclamation

162

242

A2

¢

Cent sign

163

243

A3

£

Pound sign (British currency)

164

244

A4

¤

Currency sign

165

245

A5

¥

Yen sign

166

246

A6

|

Broken bar

167

247

A7

§

Section symbol

168

250

A8

̈

Umlaut or diaeresis

169

251

A9

©

Copyright symbol

170

252

AA

ª

Feminine ordinal

171

253

AB

«

Left angle quotes

172

254

AC

¬

Logical not symbol

173

255

AD

-

Soft hyphen

174

256

AE

®

Registered trademark symbol

175

257

AF

-

Spacing macron

176

260

B0

¬

Degree sign

177

261

B1

±

Plus-minus

178

262

B2

2

Superscript 2

179

263

B3

3

Superscript 3

180

264

B4

'

Spacing acute

181

265

B5

m

Micro sign

182

266

B6

¶

Paragraph symbol

183

267

B7

·

Middle dot

184

270

B8

¸

Spacing cedilia

185

271

B9

i

Superscript 1

186

272

BA

º

Masculine ordinal

187

273

BB

»

Right angle quotes

188

274

BC

1/4

One-fourth

189

275

BD

1/2

One-half

190

276

BE

3/4

Three-fourths

191

277

BF

¿

Inverted question mark

192

300

C0

À

A with grave accent

193

301

C1

Á

A with acute accent

194

302

C2

Â

A with circumflex

195

303

C3

Ã

A with tilde

196

304

C4

Ä

A with umlaut

197

305

C5

Å

A with ring accent

198

306

C6

Æ

AE ligature

199

307

C7

Ç

C with cedilia

200

310

C8

È

E with grave accent

201

311

C9

É

E with acute accent

202

312

CA

Ê

E with circumflex

203

313

CB

Ë

E with umlaut

204

314

CC

Ì

I with grave accent

205

315

CD

í

I with acute accent

206

316

CE

Î

I with circumflex

207

317

CF

Ï

I with umlaut

208

320

D0

D

Eth (Icelandic)

209

321

D1

Ñ

N with tilde

210

322

D2

Ò

O with grave accent

211

323

D3

Ó

O with acute accent

212

324

D4

Ô

O with circumflex

213

325

D5

Õ

O with tilde

214

326

D6

Ö

O with umlaut

215

327

D7

x

Multiplication sign

216

330

D8

Ø

O with slash

217

331

D9

Ù

U with grave accent

218

332

DA

Ú

U with acute accent

219

333

DB

û

U with circumflex

220

334

DC

Ü

U with umlaut

221

335

DD

Y with acute accent

222

336

DE

Thorn (Icelandic)

223

337

DF

ß

Sharp s

224

340

E0

à

a with grave accent

225

341

E1

á

a with acute accent

226

342

E2

â

a with circumflex

227

343

E3

ã

a with tilde

228

344

E4

ä

a with umlaut

229

345

E5

å

a with ring accent

230

346

E6

æ

ae ligature

231

347

E7

ç

c with cedilia

232

350

E8

è

e with grave accent

233

351

E9

é

e with acute accent

234

352

EA

ê

e with circumflex

235

353

EB

ë

e with umlaut

236

354

EC

ì

i with grave accent

237

355

ED

í

i with acute accent

238

356

EE

î

i with circumflex

239

357

EF

ï

i with umlaut

240

360

F0

D

eth (Icelandic)

241

361

F1

ñ

n with tilde

242

362

F2

ò

o with grave accent

243

363

F3

ó

o with acute accent

244

364

F4

ô

o with circumflex

245

365

F5

õ

o with tilde

246

366

F6

ö

o with umlaut

247

367

F7

Division sign

248

370

F8

Ø

o with slash

249

371

F9

ù

u with grave accent

250

372

FA

ú

u with acute accent

251

373

FB

Û

u with circumflex

252

374

FC

ü

u with umlaut

253

375

FD

y with acute accent

254

376

FE

thorn (Icelandic)

255

377

FF

ÿ

y with umlaut


Bibliography

Many books have been written about Unix and related topics. It would be impossible to list them all, nor would that be very helpful. In this chapter, we present the "classics"--those books that the true Unix wizard has on his or her shelf. (Alas, some of these are now out of print; thus only older Unix wizards have them.)

Because Unix has affected many aspects of computing, you will find books listed here on things besides just the Unix operating system itself.

This chapter presents:

  • Unix descriptions and programmer's manuals

  • Unix internals

  • System and network administration

  • Programming with the Unix mindset

  • Programming languages

  • TCP/IP networking

  • Software development

  • Emacs

  • Standards

  • O'Reilly books


Unix Descriptions and Programmer's Manuals

  1. The Bell System Technical Journal, Volume 57 Number 6, Part 2, July-August 1978. AT&T Bell Laboratories, Murray Hill, NJ, USA. ISSN 0005-8580. A special issue devoted to Unix, by the creators of the system.

  2. AT&T Bell Laboratories Technical Journal, Volume 63 Number 8, Part 2, October 1984. AT&T Bell Laboratories, Murray Hill, NJ, USA. Another special issue devoted to Unix.

    These two volumes were republished as:

  3. UNIX System Readings and Applications, Volume 1, Prentice Hall, Englewood Cliffs, NJ, USA, 1987. ISBN 0-13-938532-0.

  4. UNIX System Readings and Applications, Volume 2, Prentice Hall, Englewood Cliffs, NJ, USA, 1987. ISBN 0-13-939845-7.

  5. UNIX Time-sharing System: UNIX Programmers Manual, Seventh Edition, Volumes 1, 2A, 2B. Bell Telephone Laboratories, Inc., January 1979.

    These are the reference manuals (Volume 1), and descriptive papers (Volumes 2A and 2B) for the landmark Seventh Edition Unix system, the direct ancestor of all current commercial Unix systems.

    They were reprinted by Holt Rinehart & Winston, but are now long out of print. However, they are available online from Bell Labs in troff source, PDF, and PostScript formats. See http://plan9.bell-labs.com/7thEdMan.

  6. UNIX Research System: Programmer's Manual, Tenth Edition, Volume 1, AT&T Bell Laboratories, M.D. McIlroy and A.G. Hume editors, Holt Rinehart & Winston, New York, NY, USA, 1990. ISBN 0-03-047532-5.

  7. UNIX Research System: Papers, Tenth Edition, Volume 2, AT&T Bell Laboratories, M.D. McIlroy and A.G. Hume editors, Holt Rinehart & Winston, New York, NY, USA, 1990. ISBN 0-03-047529-5.

    These are the manuals and papers for the Tenth Edition Unix system. Although this system was not used much outside of Bell Labs, many of the ideas from it and its predecessors were incorporated into various versions of System V. The manuals make interesting reading, in any case.

  8. 4.4BSD Manuals, Computing Systems Research Group, University of California, Berkeley. O'Reilly Media, Inc., Sebastopol, CA, USA, 1994. ISBN 1-56592-082-1. Out of print.

    The manuals for 4.4BSD.

  9. Your Unix programmer's manual. One of the most instructive things you can do is read your manual from front to back.[1] (This is harder than it used to be, as Unix systems have grown.) It is easier to do if your Unix vendor makes printed copies of its documentation available. Otherwise, start with the Seventh Edition manual, and then read your local documentation as needed.

    [1] One summer, while working as a contract programmer, I spent my lunchtimes reading the manual for System III (yes, that long ago) from cover to cover. I don't know that I ever learned so much in so little time.

  10. A Quarter Century of Unix, Peter H. Salus. Addison-Wesley, Reading, MA, USA, 1994. ISBN 0-201-54777-5.

    A delightful book that tells the history of Unix, from its inception up to the time the book was written. It reads like a good novel, except that it's all true!

  11. Linux and the Unix Philosophy, Mike Gancarz. Digital Press, Bedford, MA, USA, 2003. ISBN 1-55558-273-7.


Unix Internals

The dedicated Unix wizard knows not only how to use his or her system, but how it works.

  1. Lions' Commentary on UNIX 6th Edition, with Source Code, John Lions. Peer-To-Peer Communications LLC, Charlottesville, VA, USA, 2005. ISBN 1-57398-013-7. http://www.peerllc.com/.

    This classic work provides the source code for the Sixth Edition Unix kernel, with a complete exegesis of it. It set the standard for clear exposition of operating system internals.

  2. The Design of the UNIX Operating System, Maurice J. Bach. Prentice Hall, Englewood Cliffs, NJ, USA, 1986. ISBN 0-13-201799-7.

    This book very lucidly describes the design of System V Release 2, with some discussion of important features in System V Release 3, such as STREAMS and the filesystem switch.

  3. The Magic Garden Explained: The Internals of Unix System V Release 4: An Open Systems Design, Berny Goodheart, James Cox, and John R. Mashey. Prentice Hall, Englewood Cliffs, NJ, USA, 1994. ISBN 0-13-098138-9.

  4. Unix Internals: The New Frontiers, Uresh Vahalia. Prentice Hall, Englewood Cliffs, NJ, USA, 1996. ISBN 0-13-101908-2.

  5. Solaris Internals: Core Kernel Architecture, Jim Mauro and Richard McDougall. Prentice Hall PTR, Upper Saddle River, NJ, USA, 2000. ISBN 0-13-022496-0.

  6. UNIX(R) Systems for Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers, Curt Schimmel. Addison-Wesley, Reading, MA, USA, 1994. ISBN 0-201-63338-8.

  7. The Design and Implementation of the 4.3BSD UNIX Operating System, Samuel J. Leffler, Marshall Kirk McKusick, Michael J. Karels and John S. Quarterman. Addison-Wesley, Reading, MA, USA, 1989. ISBN 0-201-06196-1.

    This book describes the 4.3BSD version of Unix. Many important features found in commercial Unix systems first originated in the BSD Unix systems, such as long filenames, job control, and networking.

  8. The Design and Implementation of the 4.4 BSD Operating System, Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, and John S. Quarterman. Addison Wesley Longman, Reading, MA, USA, 1996. ISBN 0-201-54979-4.

    This book is an update of the previous one, for 4.4BSD, the last Unix system released from UCB. To quote from the publisher's description, the book "details the major changes in process and memory management, describes the new extensible and stackable filesystem interface, includes an invaluable chapter on the new network filesystem, and updates information on networking and interprocess communication."

  9. The Design and Implementation of the FreeBSD Operating System, Marshall Kirk McKusick and George V. Neville-Neil. Addison-Wesley, Reading, MA, USA, 2005. ISBN 0-201-70245-2.

    An update of the previous book, focusing on the FreeBSD operating system. It presents the state of current BSD operating system technology.

  10. Linux Kernel Development, Second Edition, Robert Love. Novell Press, Que Publishing, Indianapolis, IN, USA, 2005. ISBN 0-672-32720-1.

  11. Understanding the Linux Kernel, Second Edition, Daniel P. Bovet, and Marco Cesati. O'Reilly Media, Inc., Sebastopol, CA, USA, 2002. ISBN 0-596-00213-0.

  12. Linux Device Drivers, Third Edition, Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman. O'Reilly Media, Inc. Sebastopol, CA, USA, 2005. ISBN 0-596-00590-3


System and Network Administration

Unix system administration is a complicated topic in its own right. In these days of single-user workstations, even regular users also have to understand basic system administration tasks. Besides managing the system (users, filesystems, accounting), administrators also have to understand TCP/IP network administration.

  1. UNIX System Administration Handbook, Third Edition, Evi Nemeth, Garth Snyder, Scott Seebass, and Trent R. Hein. Prentice Hall PTR, Upper Saddle River, NJ, USA, 2000. ISBN 0-13-020601-6.

  2. Linux Administration Handbook, Evi Nemeth, Garth Snyder, and Trent R. Hein. Prentice Hall PTR, Upper Saddle River, NJ, USA, 2002. ISBN 0-13-008466-2.

    A revision of the previous book focused on GNU/Linux.

  3. Essential System Administration, Third Edition, Æleen Frisch. O'Reilly Media, Inc., Sebastopol, CA, USA, 2002. ISBN 0-596-00343-9.

  4. DNS and BIND, Fouth Edition, Paul Albitz and Cricket Liu. O'Reilly Media, Inc., Sebastopol, CA, USA, 2001. ISBN 0-596-00158-4.

  5. TCP/IP Network Administration, Third Edition, Craig Hunt. O'Reilly Media, Inc., Sebastopol, CA, USA, 2002. ISBN 0-596-00297-1.

  6. Linux Network Administrator's Guide, Third Edition, Tony Bautts, Terry Dawson, and Gregor N. Purdy. O'Reilly Media, Inc. Sebastopol, CA, USA, 2005. ISBN 0-596-00548-2.


Programming with the Unix Mindset

Any book written by Brian Kernighan deserves careful reading, usually several times. The first two books present the Unix "toolbox" programming methodology. They will help you learn how to "think Unix." The third book continues the process, with a more explicit Unix focus. The fourth and fifth are about programming in general, and also very worthwhile.

  1. Software Tools, Brian W. Kernighan and P. J. Plauger. Addison-Wesley, Reading, MA, USA, 1976. ISBN 0-201-03669-X.

    A wonderful book[2] that presents the design and code for programs equivalent to Unix's grep, sort, ed, and others. The programs use RATFOR (Rational FORTRAN), a preprocessor for FORTRAN with C-like control structures.

    [2] One that changed my life forever.

  2. Software Tools in Pascal, Brian W. Kernighan and P. J. Plauger. Addison-Wesley, Reading, MA, USA, 1981. ISBN 0-201-10342-7.

    A translation of the previous book into Pascal. Still worth reading; Pascal provides many things that FORTRAN does not.

  3. The Unix Programming Environment, Brian W. Kernighan and Rob Pike. Prentice Hall, Englewood Cliffs, NJ, USA, 1984. ISBN 0-13-937699-2 (hardcover), 0-13-937681-X (paperback).

    This books focuses explicitly on Unix, using the tools in that environment. In particular, it adds important material on the shell, awk, and the use of lex and yacc. See http://cm.bell-labs.com/cm/cs/upe.

  4. The Elements of Programming Style, Second Edition, Brian W. Kernighan and P. J. Plauger. McGraw-Hill, New York, NY, USA, 1978. ISBN 0-07-034207-5.

    Modeled after Strunk & White's famous The Elements of Style, this book describes good programming practices that can be used in any environment.

  5. The Practice of Programming, Brian W. Kernighan and Rob Pike. Addison Wesley Longman, Reading, MA, USA, 1999. ISBN 0-201-61586-X.

    Similar to the previous book, with a somewhat stronger technical focus. See http://cm.bell-labs.com/cm/cs/tpop.

  6. The Art of UNIX Programming, Eric S. Raymond. Addison-Wesley, Reading, MA, USA, 2003. ISBN 0-13-124085-4.

    We don't agree with everything the author says, but this book is still worth reading.

  7. Writing Efficient Programs, Jon Louis Bentley. Prentice Hall, Englewood Cliffs, NJ, USA, 1982. ISBN 0-13-970251-2 (hardcover), 0-13-970244-X (paperback).

    Although not related to Unix, this is an excellent book for anyone interested in programming efficiently.

  8. Programming Pearls, Second Edition, Jon Louis Bentley. Addison-Wesley, Reading, MA, USA, 2000. ISBN 0-201-65788-0.

  9. More Programming Pearls: Confessions of a Coder, Jon Louis Bentley. Addison-Wesley, Reading, MA, USA, 1988. ISBN 0-201-11889-0.

    These two excellent books, to quote Nelson H. F. Beebe, "epitomize the Unix mindset, and are wonderful examples of little languages, algorithm design, and much more." These should be on every serious programmer's bookshelf.

  10. Advanced Programming in the UNIX Environment, Second Edition, W. Richard Stevens and Stephen Rago. Addison-Wesley, Reading, MA, USA, 2005. ISBN 0-201-43307-9.

    A thick but excellent work on how to use the wealth of system calls in modern Unix systems.

  11. Linux Programming by Example: The Fundamentals, Arnold Robbins. Prentice Hall PTR, Upper Saddle River, NJ, USA, 2004. ISBN 0-13-142964-7.

    This book is more selective than the one by Stevens and Rago, focusing on the core systems calls and library functions used by most standard applications. Wherever possible, it uses example code from both V7 Unix and GNU software for demonstration.

  12. Advanced UNIX Programming, Second Edition, Marc J. Rochkind, Addison-Wesley, Reading, MA, USA, 2004. ISBN 0-13-141154-3.


Programming Languages

A number of important programming languages were first developed under Unix. Note again the books written by Brian Kernighan.

  1. The C Programming Language, Brian W. Kernighan and Dennis M. Ritchie. Prentice Hall, Englewood Cliffs, NJ, USA, 1978. ISBN 0-13-110163-3.

    The original "bible" on C. Dennis Ritchie invented C and is one of the two "fathers" of Unix. This edition is out of print.

  2. The C Programming Language, Second Edition, Brian W. Kernighan and Dennis M. Ritchie. Prentice Hall, Englewood Cliffs, NJ, USA, 1988. ISBN 0-13-110362-8.

    This revision of the original covers the 1990 version of Standard C. It retains and improves upon the high qualities of the first edition. See http://cm.bell-labs.com/cm/cs/cbook.

  3. C: A Reference Manual, Fifth Edition, Samuel P. Harbison III and Guy L. Steele. Prentice Hall, Upper Saddle River, NJ, USA, 2002. ISBN 0-13-089592-X.

    An excellent discussion of the details for those who need to know. This edition covers everything from the original, pre-Standard C, through the 1999 version of Standard C.

  4. The C++ Programming Language, Special Third Edition, Bjarne Stroustrup. Addison-Wesley, Reading, MA, USA, 2000. ISBN 0-201-70073-5.

    The definitive statement on C++ by the language's inventor and the ANSI C++ committee chair. See http://www.awl.com/cseng/titles/0-201-70073-5/.

  5. The C++ Standard Library—A Tutorial and Reference, Nicolai M. Josuttis. Addison-Wesley, Reading, MA, USA, 1999. ISBN 0-201-37926-0.

  6. C++ Primer, Third Edition, Stanley B. Lippman and Josée Lajoie. Addison Wesley Longman, Reading, MA, USA, 1998. ISBN 0-201-82470-1.

    This is an excellent introduction to C++. See http://www.awl.com/cseng/titles/0-201-82470-1/.

  7. The Annotated C++ Reference Manual, Margaret A. Ellis and Bjarne Stroustrup. Addison-Wesley, Reading, MA, USA, 1990. ISBN 0-201-51459-1.

    The first attempt to rigorously define the C++ language. This book became one of the base documents for the ANSI C++ standardization committee. It is now of mostly historical interest. See http://www.awl.com/cseng/titles/0-201-51459-1/.

  8. The Java Programming Language, Third Edition, Ken Arnold, James Gosling and David Holmes. Addison-Wesley, Reading, MA, USA, 2000. ISBN 0-201-70433-1.

    This book is intended for learning Java. The first two authors are two of the designers of the language.

  9. The Java Language Specification, Second Edition, James Gosling, Bill Joy, Guy L. Steele Jr. and Gilad Bracha. Addison-Wesley, Reading, MA, USA, 2000. ISBN 0-201-31008-2.

  10. The AWK Programming Language, Alfred V. Aho, Brian W. Kernighan, and Peter J. Weinberger. Addison-Wesley, Reading, MA, USA, 1987. ISBN 0-201-07981-X.

    The original definition for the awk programming language. Extremely worthwhile. See http://cm.bell-labs.com/cm/cs/awkbook.

  11. Effective awk Programming, Third Edition, Arnold Robbins. O'Reilly Media, Inc., Sebastopol, CA, USA, 2001. ISBN 0-596-00070-7.

    A more tutorial treatment of awk that covers the POSIX standard for awk. It also serves as the user's guide for gawk.

  12. Tcl and the Tk Toolkit, John K. Ousterhout. Addison-Wesley, Reading, MA, USA, 1994. ISBN 0-201-63337-X.

    The first book on Tcl/Tk. this book is now out of date, although it was written by the creator of Tcl/Tk.

  13. Practical Programming in Tcl & Tk, Fourth Edition, Brent B. Welch, Ken Jones, and Jeffry Hobbs. Prentice Hall PTR, Upper Saddle River, NJ, USA, 2003. ISBN 0-13-038560-3

  14. Effective Tcl/Tk Programming: Writing Better Programs in Tcl and Tk, Mark Harrison and Michael J. McLennan. Addison-Wesley, Reading, MA, USA, 1997. ISBN 0-201-63474-0.

  15. The New Kornshell Command and Programming Language, Morris I. Bolsky and David G. Korn. Prentice Hall, Englewood Cliffs, NJ, USA, 1995. ISBN 0-13-182700-6.

    The definitive work on the Korn shell, by its author.

  16. Hands-On KornShell 93 Programming, Barry Rosenberg. Addison Wesley Longman, Reading, MA, USA, 1998. ISBN 0-201-31018-X.

  17. Compilers—Principles, Techniques, and Tools, Alfred V. Aho and Ravi Sethi and Jeffrey D. Ullman. Addison Wesley Longman, Reading, MA, USA, 1986. ISBN 0-201-10088-6.

    This is the famous "dragon book" on compiler construction. It provides much of the theory behind the operation of lex and yacc.


TCP/IP Networking

The books by Comer are well-written; they are the standard descriptions of the TCP/IP protocols. The books by Stevens are also very highly regarded.

  1. Internetworking with TCP/IP Volume 1: Principles, Protocols, and Architecture, Fourth Edition, Douglas E. Comer. Prentice Hall, Upper Saddle River, NJ, USA, 2000. ISBN 0-13-018380-6.

  2. Internetworking With TCP/IP Volume 2: ANSI C Version: Design, Implementation, and Internals, Third Edition, Douglas E. Comer and David L. Stevens. Prentice Hall, Englewood Cliffs, NJ, USA, 1998. ISBN 0-13-973843-6.

  3. Internetworking With TCP/IP Volume 3: Client-Server Programming and Applications: Linux/Posix Sockets Version, Second Edition, Douglas E. Comer, David L. Stevens, Marshall T. Rose, and Michael Evangelista. Prentice-Hall, Englewood Cliffs, NJ, USA, 2000. ISBN 0-13-032071-4.

  4. TCP/IP Illustrated, Volume 1: The Protocols, W. Richard Stevens. Addison Wesley Longman, Reading, MA, USA, 1994. ISBN 0-201-63346-9.

  5. TCP/IP Illustrated, Volume 2: The Implementation, W. Richard Stevens and Gary R. Wright. Addison Wesley Longman, Reading, MA, USA, 1995. ISBN 0-201-63354-X.

  6. TCP/IP Illustrated, Volume 3: TCP for Transactions, HTTP, NNTP, and the Unix Domain Protocols, W. Richard Stevens. Addison Wesley Longman, Reading, MA, USA, 1996. ISBN 0-201-63495-3.

  7. Unix Network Programming, Volume 1: The Sockets Networking API, Third Edition W. Richard Stevens, Bill Fenner and Andrew M. Rudoff. Addison-Wesley, Reading, MA, USA, 2003. ISBN 0-13-141155-1.

  8. Unix Network Programming, Volume 2: Interprocess Communications, Second Edition, W. Richard Stevens. Prentice Hall PTR, Upper Saddle River, NJ, USA, 1998. ISBN 0-13-081081-9.


Software Development

  1. Applying RCS and SCCS, Don Bolinger and Tan Bronson. O'Reilly Media, Inc., Sebastopol, CA, USA, 1995. ISBN 1-56592-117-8.

  2. Open Source Development with CVS, Third Edition, Karl Fogel and Moshe Bar. Paraglyph Press, Phoenix, AZ, USA, 2003. ISBN 1932111816.

    This book is available online: see http://cvsbook.red-bean.com/.

  3. Essential CVS, Jennifer Vesperman. O'Reilly Media, Inc., Sebastopol, CA, USA, 2003. ISBN 0-596-00459-1.

  4. Version Control With Subversion, Ben Collins-Sussman, Brian W. Fitzpatrick and C. Michael Pilato. O'Reilly Media, Inc., Sebastopol, CA, USA, 2004. ISBN 0-596-00448-6.

  5. GNU Make: A Program for Directing Recompilation, Richard M. Stallman, Roland McGrath, and Paul D. Smith. The Free Software Foundation, Cambridge, MA, USA, 2004. ISBN 1-882114-83-3.

  6. Managing Projects with GNU make, Third Edition, Robert Mecklenburg, Andy Oram, and Steve Talbott. O'Reilly Media, Inc., Sebastopol, CA, USA, 2005. ISBN 0-596-00610-1.

  7. Debugging with GDB: The GNU Source-Level Debugger, Richard M. Stallman, Roland Pesch, Stan Shebs, et al. The Free Software Foundation, Cambridge, MA, USA, 2002. ISBN 1-882114-88-4.

  8. The Cathedral and the Bazaar, Eric S. Raymond, O'Reilly Media, Inc., Sebastopol, CA, USA, 2001. ISBN 0-596-00131-2 (hardback), 0-596-00108-8 (paperback).


Emacs

  1. GNU Emacs Manual, for Version 21, Fifteenth Edition, Richard M. Stallman. The Free Software Foundation, Cambridge, MA, USA, 2002. ISBN 1-882114-85-X.

  2. An Introduction to Programming in Emacs Lisp, Revised Second Edition, Robert J. Chassell. The Free Software Foundation, Cambridge, MA, USA, 2004. ISBN 1-882114-56-6

  3. GNU Emacs Lisp Reference Manual (in two volumes), Bil Lewis, Dan LaLiberte, Richard Stallman, and the GNU Manual Group. The Free Software Foundation, Cambridge, MA, USA, 2000. ISBN 1-882114-73-6. Out of print.

  4. Learning GNU Emacs, Third Edition, Debra Cameron, James Elliott, and Marc Loy. O'Reilly Media, Inc., Sebastopol, CA, USA, 2005. ISBN 0-596-00648-9.

  5. Writing GNU Emacs Extensions, Bob Glickstein. O'Reilly Media, Inc., Sebastopol, CA, USA, 1997. ISBN 1-56592-261-1.

  6. GNU Emacs: UNIX Text Editing and Programming, Michael A. Schoonover, John S. Bowie, and William R. Arnold. Addison-Wesley, Reading, MA, USA, 1992. ISBN 0-201-56345-2.


Standards

There are a number of "official" standards for the behavior of portable applications among Unix and Unix-like systems. The first entry is the current POSIX standard. The rest are the formal standards for the C and C++ programming languages.

  1. IEEE Standard 1003.1-2004: Standard for information Technology—Portable Operating System Interface (POSIX®). IEEE, New York, NY, USA, 2004.

    This is the POSIX standard. It combines both the system call interface standard and the shell and utilities standard in one document. The standard consists of several volumes: Base Definitions (Volume 1), System Interfaces (Volume 2), Shell and Utilities (Volume 3), and Rationale (Volume 4).

    The standard may be ordered from http://www.standards.ieee.org on CD-ROM (Product number SE95238, ISBN 0-7381-4049-X) or as PDF (Product number SS95238, ISBN 0-7381-4048-1).

  2. X3 Secretariat: Standard—The C Language. X3J11/90-013. ISO Standard ISO/IEC 9899. Computer and Business Equipment Manufacturers Association. Washington DC, USA, 1990.

  3. International Standard: Programming Languages—C. ISO Standard ISO/IEC 9899:1999(E). Information Technology Industry Council, Washington DC, USA, 1999.

    These two documents are the 1990 and 1999 standards for the C language. It generally takes five or more years from when a language standard is published until compilers for that version become widely available.

  4. X3 Secretariat: International Standard—The C++ Language. X3J16-14882. Information Technology Council (NSITC). Washington DC, USA, 1998.

    This is the initial standard for the C++ programming language, used by most C++ compilers as of this writing.

  5. International Standard: Programming Languages—C++. ISO Standard ISO/IEC 14882-2003. Information Technology Industry Council, Washington DC, USA, 2003.

    A revision of the previous document.


O'Reilly Books

Here is a list of O'Reilly Media books cited throughout this book. There are, of course, many other O'Reilly books relating to Unix. See http://www.oreilly.com/catalog.

  1. Advanced Perl Programming, Second Edition, Simon Cozens. O'Reilly Media, Inc., Sebastopol, CA, USA, 2005. ISBN 0-596-00456-7

  2. Checking C Programs with lint, Ian F. Darwin. O'Reilly Media, Inc., Sebastopol, CA, USA, 1988. ISBN 0-937175-30-7.

  3. Classic Shell Scripting, Arnold Robbins and Nelson H.F. Beebe. O'Reilly Media, Inc., Sebastopol, CA, USA, 2005. ISBN 0-596-00595-4.

  4. Learning Perl, Third Edition, Randal L. Schwartz and Tom Phoenix. O'Reilly Media, Inc., Sebastopol, CA, USA, 2001. ISBN 0-596-00132-0.

  5. Learning the bash Shell, Third Edition, Cameron Newham and Bill Rosenblatt. O'Reilly Media, Inc., Sebastopol, CA, USA, 2005. ISBN 0-596-00965-8.

  6. Learning the Korn Shell, Second Edition, Bill Rosenblatt and Arnold Robbins. O'Reilly Media, Inc., Sebastopol, CA, USA, 2002. ISBN 0-596-00195-9.

  7. Learning Python, Second Edition, Mark Lutz and David Ascher. O'Reilly Media, Inc., Sebastopol, CA, USA, 2003. ISBN: 0-596-00281-5.

  8. Learning the Unix Operating System, Fifth Edition, Jerry Peek, Grace Todino, and John Strang. O'Reilly Media, Inc., Sebastopol, CA, USA, 2001. ISBN 0-596-00261-0.

  9. Learning the vi Editor, Sixth Edition, Linda Lamb and Arnold Robbins. O'Reilly Media, Inc., Sebastopol, CA, USA, 1998. ISBN 1-56592-426-6.

  10. lex & yacc, Second Edition, John Levine, Tony Mason, and Doug Brown. O'Reilly Media, Inc., Sebastopol, CA, USA, 1992. ISBN 1-56592-000-7.

  11. Linux in a Nutshell, Fifth Edition, Ellen Siever, Aaron Weber, Stephen Figgins, Robert Love, and Arnold Robbins. O'Reilly Media, Inc., Sebastopol, CA, USA, 2005. ISBN 0-596-00482-6.

  12. Mac OS X Panther in a Nutshell, Second Edition, Jason McIntosh, Chuck Toporek, and Chris Stone. O'Reilly Media, Inc., Sebastopol, CA, USA, 2004. ISBN 0-596-00606-3.

  13. Mastering Regular Expressions, Second Edition, Jeffrey E. F. Friedl. O'Reilly Media, Inc., Sebastopol, CA, USA, 2002. ISBN 0-596-00289-0.

  14. PGP: Pretty Good Privacy, Simson Garfinkel. O'Reilly Media, Inc., Sebastopol, CA, USA, 1994. ISBN 1-56592-098-8.

  15. Programming Perl, Third Edition, Larry Wall, Tom Christiansen, and Jon Orwant. O'Reilly Media, Inc., Sebastopol, CA, USA, 2000. ISBN 0-596-00027-8.

  16. Programming Python, Second Edition, Mark Lutz. O'Reilly Media, Inc., Sebastopol, CA, USA, 2001. ISBN: 0-596-00085-5.

  17. sed & awk, Second Edition, Dale Dougherty and Arnold Robbins. O'Reilly Media, Inc., Sebastopol, CA, USA, 1997. ISBN 1-56592-225-5.

  18. SSH, The Secure Shell, The Definitive Guide, Second Edition, Daniel J. Barrett, Richard E. Silverman, and Robert G. Byrnes. O'Reilly Media, Inc., Sebastopol, CA, USA, 2005. ISBN: 0-596-00895-3.

  19. Using csh & tcsh, Paul DuBois. O'Reilly Media, Inc., Sebastopol, CA, USA, 1995. ISBN 1-56592-132-1.


About the Author

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. His experience also includes multiple commercial Unix systems, from Sun, IBM, HP, and DEC. He has been working with GNU/Linux systems since 1996, and for this book was introduced to the joys of the Macintosh. (iTunes is now his current favorite "killer app.")

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.

In previous incarnations he has been a systems administrator and a teacher of Unix and networking Continuing Education classes. He has also had more than one poor experience with start-up software companies, which he prefers not to think about anymore. These days he writes high-end Command and Control- related software for a leading Isreali software compnay. One day he hopes to put up his own web site at http://www.skeeve.com.

O'Reilly has been keeping him busy; he is author and/or coauthor of these bestselling titles: Learning the vi Editor, Effective awk Programming, sed & awk, Classic Shell Scripting, and several pocket references.


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]

Previous Section < Day Day Up >


index_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]

#define statements (C), generating template file of
$ENV file (read by Korn and Bash shells at startup)
& (ampersand)
&& (logical AND) operator 2nd 3rd 4th
&= (assignment) operator 2nd
background execution, Bash and ksh 2nd
background execution, tcsh
bitwise AND operator 2nd
ex command
redirection symbol, Bash and ksh
redirection symbol, tcsh
replacement pattern metacharacter
< > (angle brackets)
< > redirection operator, Bash and ksh 2nd
* (asterisk)
** exponentiation operator 2nd
*= (assignment) operator 2nd 3rd
filename metacharacter, Bash and ksh
filename metacharacter, tcsh 2nd
multiplication operator 2nd 3rd
Unix metacharacter 2nd
@ (at command)
ex
tcsh 2nd
@ (at sign)
array operator
filename metacharacter, Bash and ksh
` (backquote)
command substitution in Bash and ksh
command substitution in tcsh
\ (backslash)
filename metacharacter
line continuation in makefile
quoting in Bash and ksh
quoting in tcsh
replacement pattern metacharacter
search pattern metacharacter 2nd
/bin/sh (Bourne shell)
{ } (braces)
groups of commands
ksh93 variable names containing . (dot)
search pattern metacharacters
string expansion characters, tcsh
Unix metacharacter
[ ] (brackets)
[[ ]] command (Bash and ksh)
[[.c.]] notation, specifying collating sequences
[[=c=]] notation, matching characters with same weight
enclosing array elements, Bash and ksh
filename metacharacters, tcsh 2nd
Unix metacharacters 2nd
^ (caret)
^= (assignment) operator 2nd 3rd
bitwise exclusive OR operator 2nd
exponentiation operator
filename metacharacter, tcsh 2nd
quick substitution, tcsh
search pattern metacharacter
Unix metacharacter
[[:class:]] (character classes)
: (colon)
ex commands 2nd
null command, Bash and ksh
sed command
tcsh command
, (comma) operator
$ (dollar sign)
$" ", quoting in Bash and Korn shells
$' ', quoting in Bash and Korn shells
${ ... } syntax, referencing arrays
built-in Bash and Korn shell variable names
field reference operator
GDB convenience variable names
GDB value history
make utility macro names
make utility, in command lines
search pattern metacharacter 2nd
variable substitution in Bash and ksh
variable substitution in tcsh
. (dot)
Bash and ksh command
ksh93 variable names containing
Unix metacharacter 2nd
= (equal sign)
= = equality operator 2nd 3rd
=~ string equality, tcsh
assignment operator 2nd 3rd
ex command
sed command
! (exclamation mark)
!= (inequality) operator 2nd 3rd
!~ regular expression nonmatch, awk
!~ string inequality, tcsh
ex command
expanded to current command number in Korn shell
filename metacharacter, Bash and ksh 2nd
history substitution, tcsh
negating pipeline, ksh and Bash
negation in sed
NOT operator 2nd 3rd
redirection symbol, tcsh
# (hash mark)
#! command, invoking named shell
#! command, invoking tcsh shell
comments
awk
Bash and ksh
sed
tcsh
- (hyphen)
- - (auto-decrement) operator 2nd 3rd
-= (assignment) operator 2nd 3rd
filename metacharacter, Bash and ksh
negation operator
subtraction operator 2nd 3rd
tag names and (cvs)
< (left angle bracket)
<& (file descriptor), Bash and ksh
<< bitwise left shift operator 2nd
<< redirection operator 2nd
<<< redirection operator
<<= (assignment) operator
<= (less than or equal to) operator 2nd 3rd
ex command
less than operator 2nd 3rd
redirection operator 2nd 3rd
( ) (parentheses)
command grouping, Bash and ksh 2nd
command grouping, tcsh
enclosing make utility macro names
Unix metacharacter 2nd
% (percent)
%= (assignment) operator 2nd 3rd
modulus operator 2nd 3rd
pattern rules in makefile lines
replacement pattern metacharacter (ed)
| (pipe character)
Bash and ksh
bitwise OR operator 2nd
redirecting command output 2nd
tcsh shell
Unix metacharacter 2nd
|& (execute coprocesses in ksh)
|& (multiple redirection)
|= (assignment) operator 2nd
|| (logical OR) operator 2nd 3rd 4th
+ (plus sign)
++ (auto-increment) operator 2nd 3rd
+= (assignment) operator 2nd 3rd
addition operator 2nd 3rd
filename metacharacter, Bash and ksh
unary operator
Unix metacharacter 2nd
? (question mark)
?: (inline conditional evaluation) 2nd
filename metacharacter, Bash and ksh
filename metacharacter, tcsh 2nd
search pattern metacharacter 2nd
" " (quotation marks, double)
quoting in Bash and ksh
quoting in tcsh
' ' (quotation marks, single)
quoting in Bash and ksh
quoting in tcsh
"r" (remote) commands
> (right angle bracket)
>! redirection operator
>& (multiple redirection) 2nd
>&! (multiple redirection)
>= (greater than or equal to) operator 2nd 3rd
>> bitwise right shift operator 2nd
>> redirection operator 2nd
>>! redirection operator
>>& (multiple redirection)
>>&! (multiple redirection)
>>= (assignment) operator
>| redirection operator
ex command
greater than operator 2nd 3rd
redirection operator 2nd 3rd
; (semicolon) command separator 2nd 3rd
/ (slash)
/= (assignment) operator 2nd 3rd
division operator 2nd 3rd
~ (tilde)
binary inversion operator
bitwise negation operator
ex command
filename metacharacter, Bash and ksh
filename metacharacter, tcsh
home directories in Bash and ksh
home directories in tcsh 2nd
home directory in CVS
regular expression match operator
replacement pattern metacharacter
_ (underscore), tag names and
. (dot) files
.#file.revision
.#filename.revision file
.cshdirs file (tcsh)
.cshrc file (tcsh)
.cvsignore file (CVS)
.cvspass file (CVS)
.cvsrc file (CVS)
.cvswrappers file (CVS)
.exrc file (vi)
.gdbinit file (GDB)
.history file (tcsh)
.inputrc file
.login file (tcsh)
.logout file (tcsh)
.plan file
.profile file
shell variables, Bash and ksh
.project file
.rhosts file
.so requests, eliminating in nroff or troff files
.tcshrc file
example
/bin/ksh
/etc/bash_completion file
/etc/passwd file
Bash and ksh
tcsh
/etc/profile file
/usr/lib/rpm/rpmrc file
:set command (vi)
@include statements, gawk

Previous Section < Day Day Up >


index_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)
abbreviations commands (Emacs)
ABI (Application Binary Interface)
access mode for files, changing
access time for files, updating
aclocal command
actions, awk 2nd
simple pattern-action examples
active processes, reports on
Ada programming language, compiling
add command
CVS
svn
add-symbol-file command (GDB)
addresses for ex commands
addresses for sed commands
admin command (CVS)
advance command (GDB)
alias command
Bash and Korn shells
tcsh
aliases (command)
removing
special, for tcsh commands
aliasing variables
alloc command (tcsh)
alnum character class
alpha character class
Alt key (Emacs commands)
and function (gawk)
AND operator
& (bitwise AND) 2nd
&& (logical AND) 2nd 3rd
annotate command (CVS)
annotation processing tool (apt)
ANSI/VT100 terminal emulation, enabling (screen)
Apache 2.0 httpd web server, use with Subversion
append command (ex)
appending to files 2nd
appletviewer Java command
Application Binary Interface (ABI)
application defaults on Mac OS X
apply Mac OS command
apropos command
GDB
Unix
APT (Advanced Package Tool)
apt Java command
apt- commands, options
apt-cache command
apt-cdrom command
apt-config command
apt-extracttemplates command
apt-ftparchive command
apt-get command 2nd
apt-sortpkgs command
aptitude command 2nd
ar command
arbitrary-precision arithmetic, performing with bc
Arch (source code management system)
archives
copying
disassembling
Java
adding digital signature
jar command
maintenance (ar)
Portable Archive Exchange (pax)
removing information from (strip)
shell archive, producing
tar (tape archive)
zip command
ZIP format, printing information about
args command (ex)
arguments
Bash and Korn shells
tcsh shell
arithmetic expressions
Bash and ksh
tcsh shell
arithmetic operators
awk 2nd
Bash and ksh
tcsh
array constants
array operator (@)
arrays
Bash and Korn shells
in awk
tcsh shell
arrow keys, navigating ksh command history
as command
asort function (gawk)
asorti function (gawk)
aspell command 2nd
assembly language processing
as command
cc command
assignment operators
awk
Bash and ksh
tcsh
associative arrays
awk
at (@) command (ex)
at command
AT&T Research, ksh93
atan2 function (awk)
atomic commits
atq command
atrm command
attach command (GDB)
authentication agent
adding RSA or DSA identities
allowing/disabling forwarding of connection
ssh-agent command
authentication keys, generating for ssh
author command (svnlook)
autoconf command
aclocal command and
autoheader
Autoconf software suite
autoheader command
autoload command (ksh)
automake command
awatch command (GDB)
awk command
awk programming language
actions
command-line syntax
features
functions and commands, alphabetical summary
functions and commands, group listing
gawk command
implementation limits
nawk command 2nd
new and old versions
operators
pattern-action examples
patterns
patterns and actions
printf formats
redirections
source code for four versions and GNU gettext
user-defined functions
variable and array assignment
escape sequences
variables, built-in

Previous Section < Day Day Up >


index_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)
background processes, waiting for completion of
backtrace command (GDB)
banner command
basename command
Bash (Bourne-Again shell)
arithmetic expressions
bash command
command execution
command history
line-edit mode
programmable completion
command syntax
commands, built-in
features differing from ksh and tcsh
features in common with ksh and C shells
filename metacharacters
functions
history of
invoking
arguments
as sh
common options
options unique to Bash
job control
overview of features
quoting
characters used for
redirection syntax
setting restrictions on
syntax
special files
variables
arrays
built-in
other shell variables
special prompt settings
variable substitution
version 3
batch command
batch execution
at specified date/time
printing queued jobs
removing queued jobs
bc command
bdelete command (ex)
bg command
Bash and Korn shells
tcsh shell 2nd
biff command
bind command (Bash)
bindkey command (tcsh)
bindtextdomain function (gawk)
bison command
bitwise operators (tcsh)
blame command (svn)
blank character class
blank lines in makefiles
block size (characters)
bootstrapping problem with Subversion
Bourne family of shells
Bourne shell
history of
branch 2nd
branching and tagging improvements, Subversion
branching commands (sed)
break command
awk
Bash and Korn shells
GDB
tcsh
breakpoints
breaksw command (tcsh)
BSD (Berkeley Software Distribution)
printing commands
"r" commands
BSD Compatibility Package (Solaris)
bt (backtrace) command (GDB)
buffer command (ex)
buffer-manipulation commands (Emacs)
buffers (Emacs)
buffers command (ex)
build process for software
built-in shell variables
Bash and ksh
tcsh
sample .tcshrc file
built-ins command (tcsh)
builtin command
Bash
ksh
bundling commands
byacc Linux command
bye command (tcsh)
bzip2 command

Previous Section < Day Day Up >


index_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 (continue) command (GDB)
C and C++ languages
call-graph profile data
compilers
compiling source files
compiling with gcc
extracting messages from
lexical analysis program for C statements
c command (sed)
C shells
features in common with Korn and Bash shells
tcsh
c, d, and y editing operators (vi) 2nd
cal command
calculator commands
bc command
dc command
Caldera package manager
calendar command
calendars
call command (GDB)
call-graph profile data, C programs
caller command (Bash)
cancel command
canceling commands (Emacs)
capitalization commands (Emacs)
case command
Bash and Korn shells
tcsh
case-sensitivity
flags
Mac OS X filesystem and
setting for GDB
cat command
svn
svnlook
catch command (GDB)
catchpoints
cc command
cd command
Bash and Korn shells
ex
GDB
tcsh
CD-ROM, ejecting
cdda2wav Linux command
CDE (Common Desktop Environment)
cdparanoia Linux command
cdrdao Linux command
cdrecord Linux command
cdrw Solaris command
center command (ex)
centering commands (Emacs)
certificate management utility (keytool)
change command (ex)
changed command (svnlook)
changing directory
channels
character classes
listed
matching in Bash and Korn shells
character sets
ASCII
converting
ISO 8859-1 (Latin-1)
characters
buffer block size
converting DOS to ISO
converting ISO to DOS
counting in files
chdir command (tcsh)
check-update command (yum)
checking in files
CVS 2nd
RCS 2nd
Subversion
checking out files
CVS 2nd
from Subversion
RCS 2nd
checkout command
CVS
RCS
svn
checksums
MD5, computing or checking
SHA1, computing or checking
chflags Mac OS command
chfn Mac OS command
chgrp command
chkey Solaris command
chmod command
chown command
chpass Mac OS command
chsh Mac OS command
ci command (RCS) 2nd
cksum command
class files (Java), disassembling
classifying files by data type
clean command (yum)
cleanup command (svn)
clear command
GDB
clearing the screen
client environment variables (CVS)
client/server networking, source code management
close command (ex)
close function (awk)
cmp command
cntrl character class
co command (RCS) 2nd
Codeville (version control system)
collating sequences, specified by [[.c.]]
columns
merging file lines into
selecting from files
combining files
comm command
command command
command history
GDB
ksh and Bash shells
line-edit mode
tcsh shell
command line
invoking nroff/troff
manipulation in Bash and ksh
manipulation in tcsh
command line macros (make), overriding
command lines (makefile)
writing
command mode (telnet)
command mode (vi)
command substitution
Bash and ksh 2nd 3rd
tcsh
examples
command-line editor
Bash and ksh
tcsh
command-line interface (CLI), GDB
commands
aliases for 2nd 3rd
awk
alphabetical summary
group listing
Bash and Korn shells
forms of
job control
basic, listing of
bundled arguments
covered in the quick reference
CVS
Debian Package Manager
descriptions of, displaying
Emacs editor
Control and Meta keys
essential, listing of
listed by category
listed by key
listed by name
ex editor
executing
after logout 2nd 3rd
Bash and Korn shells
wait between
GDB
alphabetical summary
set and show commands
summarized by category
GNU/Linux, alphabetical summary
Java, summary of
lower priority, executing
Mac OS X, summary of
RCS
overview
running repeatedly (watch)
sed editor
alphabetical listing
by category
syntax
Solaris
alphabetical summary
compliant with POSIX standard
package management
Solaris 10 installs
Subversion
svn subcommands
svnadmin
svnlook
tcsh shell
job control
type, showing 2nd
Unix, summary of common
vi editor
status line
syntax
yum
commands command (GDB)
comments
awk
Bash and Korn shells
makefiles
nroff/troff
sed editor
tcsh shell
commit command
CVS
svn
commits, atomic
committing changes
Common Desktop Environment (CDE)
common synonyms (CVS subcommands)
communication commands
Compact Disc audio files, reading as WAV, AIFF, AIFF-C, or raw format files
Compact Disc Digital Audio (CDDA), converting to WAV
comparison commands
cmp
comm
diff 2nd
svn
svnlook
diff3
dircmp
RCS
rcsdiff
rdiff
sdiff
vimdiff
comparison operators
awk
Bash and ksh
tcsh
compgen command (Bash)
compilers
bc
gcc
javac
rmic (Java)
compiling C source files
compl function (gawk)
complete command
Bash
GDB
tcsh
completion facilities
Bash 2nd
tcsh shell
compression
commands for Zip files
gunzip command
gzip command
uncompressing files with zcat
unzip command
zip command
condition command (GDB)
conditional statements (makefile) 2nd
configuration
autoconf command
RCS commands for
configuration files
rpm command
vi
configuration variables, system
configure shell script
conflicts, source code changes 2nd
resolution methods in CVS
cont (continue) command (GDB)
continue command
awk
Bash and Korn shells
GDB
tcsh
control assignments (terminal)
control modes (terminal)
Control-key commands (Emacs) 2nd
convenience variables 2nd
conversation between users
converting
character sets
characters
DOS to ISO
ISO to DOS
spaces to tabs
tabs to spaces
files into tables
number units
Coordinated Universal Time (UTC)
coprocesses
gawk
Korn shell
copy command
ex
svn
copy, modify, merge model
CVS
Subversion
version control systems
copying
file archives
files
remotely
hotcopy command, svnadmin
standard input
core file
core images, creating
core-file command (GDB)
cos function (awk)
cp command
cpio command
CRCs (cyclic redundancy checks)
create command (svnadmin)
crontab command
csh (C shell) 2nd 3rd
csh.login file (tcsh)
csh.logout file (tcsh)
csplit command
CSSC (source code management system)
ctags command
CTRL-Z command
Bash and ksh
tcsh
CUPS (Common Unix Printing System)
cancel command
lp command
lpq command
lpr command
lprm command
lpstat command
curl command 2nd
current date/time
current system name
cursor-movement commands (Emacs)
cut and paste
Emacs
sed editor
vi editor
cut command
CVS (Concurrent Versions System) 2nd
command-line syntax and options
common subcommand options
commands, alphabetical summary
commands, quick start guide
copy, modify, merge model 2nd
CVSROOT variables
environment variables
internal variables
shell variables in files
dates
legal date keywords
dot files
environment variables
client
server
keywords and keyword modes
stickiness
time zones
wrappers
cyclic redundancy checks (CRCs)

Previous Section < Day Day Up >


index_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 (delete) command
ex
GDB
sed
D command (sed)
d editing operator (vi) 2nd
DAO (disk-at-once) mode
data classification of files
dates and times
access time and modification timestamp
at command
calendars
crontab command
CVS dates
CVS time zones
date command
date command (svnlook)
leave command
sleep command
specifying on RCS check-ins
time command 2nd 3rd
timex command, system usage information
uptime command
dc command
dcgettext function (gawk)
dcngettext function (gawk)
dd command
ddd (Data Display Debugger)
Debian Package Manager 2nd
command summary
files
package flags
package names
package priorities
package/selection states
shell and Perl scripts
tools, listed
debugger, defined
debugging tools
gprof
jdb (Java debugger)
ltrace Linux command
patch command
strace Linux command
declare command (Bash)
decrypt Solaris command
default command (tcsh)
defaults Mac OS command
define command (GDB)
delete command
awk
ex
GDB
svn
deleting directories
deletion commands (Emacs)
deltify command (svnadmin)
demangling names 2nd
dependencies
GNU make 2nd
listing dynamic (ldd command)
dependency lines (makefile)
desk calculator program (dc)
Desktop Korn shell
detach command (GDB)
Developer Tools, Mac OS X
development branch
development tools, Mac OS X
df command
dgettext function
diff command
CVS
svn
svnlook
diff3 command
dig command
digest Solaris command
digit character class
digital signature, adding to a .jar file
dir command
GDB
Linux
dircmp Solaris command
dircolors Linux command
directories
changing
comparing contents with dircmp
copying with ditto
creating
deleting
listing contents of (dir)
moving or renaming
navigating 2nd
printing full pathname of current
printing names of
Solaris commands
synchronizing between different computer systems 2nd
directory command (GDB)
directory versioning
dirname command
dirs command
Bash
tcsh
dirs-changed command (svnlook)
dis (disable) command (GDB)
dis Solaris command
disable command (GDB)
disassemble command (GDB)
disassembling Java class files
disassembling object files
discipline functions (ksh93)
disk-at-once (DAO) mode
disks
copying archive files
ejecting
formatting
free space, reporting on (df)
usage information (du)
disown command (Bash)
disown command (ksh93)
display command (GDB)
ditroff program
ditto Mac OS command
DNS (Domain Name Service), querying servers with dig
do (shell keyword)
do command
awk
GDB
DocBook/XML file, converting to formatted file
document command (GDB)
documentation
accessing with info command
Java language
looking up commands in manpages with whatis
done (shell keyword)
dont-repeat command (GDB)
dos2unix command
dot (.) files
down command (GDB)
down-silently command (GDB)
dpkg command 2nd
actions
actions, dpkg-deb
options
query actions
dpkg-deb command 2nd
dpkg-query command
dpkg-split command
DSA identities, adding to authentication agent
dselect command 2nd
du command
dump command (svnadmin)
dumps, octal
dvdrecord Linux command
dynamic dependencies, listing (ldd)

Previous Section < Day Day Up >


index_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 (edit) command (GDB)
e command (sed)
echo command
Bash
GDB
Korn shell
tcsh
echotc command (tcsh)
ed text editor
edit command
CVS
ex
GDB
editing, keyboard shortcuts for
editors
stream (sed)
tcsh command-line editor
text
Emacs
ex
vi 2nd
editors command (CVS)
egrep command
pattern-matching metacharacters
quoting regular expressions
eject command
ellipsis tcsh shell variable
else (shell keyword) 2nd
else command (GDB)
elvis text editor
emacs command
Emacs editor
Bash and ksh command-line editing mode
bindings, compared to vi bindings
buffer and window
command-line syntax
commands
essential, listing of
summary by category
summary by key
summary by name
keys and keystrokes for commands
kill and yank
modes
point and mark
tcsh command-line editing mode
email messages
automatic replies to
mail notification
reading and sending
enable command
Bash
GDB
encoded files, recreating original file
encrypt Solaris command
end (tcsh reserved word)
end command (GDB)
endif (tcsh reserved word)
endsw (tcsh reserved word)
enhance Solaris command
ENTER command (ex)
env command
environment variables
CVS
client
server
CVSROOT directory
modifying values
printing values of
RCS
tcsh shell
environment, displaying
equal sign
=- last entry in directory stack (tcsh)
esac (shell keyword)
Escape key (Emacs commands)
escape sequences
awk strings and regular expression constants
Bash processing of PS1, PS2, and PS4 values
echo command
GNU utilities
text quoted with $' '
troff
valid anywhere
valid only in regular expressions
etags command
eval command
Bash and Korn shells
tcsh
evaluating arguments and expressions
evim command
ex editor 2nd 3rd
addresses for commands
command options
command syntax
commands, alphabetical summary of
pattern-matching metacharacters
search-and-replace examples
starting vi from
exec command
Bash and Korn shells
tcsh
exec file (GDB)
exec-file command (GDB)
executable files, shared objects for
executable object module, combining object files into
executing commands
after logout
of lower priority
wait between
executing Java bytecode
exit command
awk
Bash and Korn shells
tcsh
exit status
commands
exp function (awk)
expand command
export command
CVS
svn
exporting make utility macros
expr command
expressions
Bash and ksh 2nd 3rd
evaluating
GDB
tcsh shell
@ command examples
if and while statements (examples)
operators
.exrc file (vi)
example
extension function (gawk)
extracting columns/fields from files
Exuberant ctags

Previous Section < Day Day Up >


index_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]

f (frame) command (GDB)
factor command
false command 2nd
Fast Lexical Analyzer Generator (flex) command
fc command 2nd
fdformat command
fflush function (gawk)
fg command
Bash and Korn shells
GDB
tcsh shell 2nd
fgrep command
fi (shell keyword)
figlet program
/etc/passwd file
.profile file
file command
ex
GDB
file creation mode mask
file descriptors
file flags, changing
file inclusion facility, gawk
file inquiry operators (tcsh)
file management commands
chgrp
chmod
chown
csplit
Emacs
GDB
split
vi
file properties (Subversion)
file resolution (GDB)
filename command
filename metacharacter, Bash and ksh
filenames
metacharacters
Bash and Korn shells
pattern matching vs.
tcsh
reducing pathnames to
stripping from pathnames
temporary, generating for use in script
.po files
files
access and modification times, updating
access modes, changing (chmod)
calculating checksum
classifying by data type
comparing
comm command
diff command
diff3 command
sdiff command
vimdiff command
compiling
converting
character sets
DOS to ISO
ISO to DOS
converting into tables with yacc
copying
ditto command
remotely
securely between network hosts
to or from tape
counting words/characters/lines of
crontab files
deleting with rm
disassembling
display format options (hexdump)
displaying by page
dot files
encoded, recreating original file
extracting columns/fields with cut
formatting lines in
formatting with pr command
joining similar lines of
linking
listing
for current directory
those to be executed
listing shared objects for
merging lines into columns
moving or renaming
name list (symbol table), printing
numbering lines in
object files, displaying profile data for
overwriting to make unrecoverable
ownership of
changing (chown)
paging
printing
appending to
initial lines of
last lines of
lp command
pseudonyms (links) for
removing duplicate lines
removing information from
removing with srm
renaming
retrieving from Internet
curl command 2nd
wget command 2nd
searching for with find
size of
sorting
splitting into multiple files
based on size
synchronizing across network connection 2nd
uncompressing with zcat
filesync Solaris command
filesystem-related parameters
filesystems
ISO 9660/Joliet/HFS filesystem
mount command
mounting
GNU/Linux 2nd
Mac OS X
Solaris
Unix, serving to Windows systems
unmounting 2nd
GNU/Linux umount
Mac OS X
Solaris
filetest command (tcsh)
find command
finger command
finish command (GDB)
Fink package manager
Aqua-based GUI
flags
changing file flags
Debian packages
format specifiers for printf and sprintf
flex (Fast Lexical Analyzer Generator) command
floppy disks
ejecting
formatting
fmt command
fo (forward-search) command (GDB)
focus command (GDB)
fold command (ex)
foldclose command (ex)
foldopen command (ex)
for command (awk)
for loop
for shell keyword
foreach command (tcsh)
format specifiers for printf and sprintf
formatting disks and memory cards
formatting files with pr command
formatting text (fmt command)
Fortran programming language, compiling (gcc)
forward-search command (GDB)
frame command (GDB)
free disk space, reporting
freshen options (rpm)
FTP (File Transfer Protocol), secure transfer using ssh (sftp)
ftp command
function (shell keyword)
function command (awk)
functions
awk
alphabetical summary
group listing
built-in mathematical functions (ksh93)
discipline functions (ksh93)
GNU make, for text manipulation
listing names (ctags)
user-defined, in awk
functions command (ksh)

Previous Section < Day Day Up >


index_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
gawk Linux command
gawk programming language
features
features specific to
coprocesses and sockets
file inclusion
internationalization
profiling
format specifiers for printf and sprintf
important options
octal and hexadecimal constants
source code URLs
variables, built-in
GCC (GNU Compiler Collection) 2nd
general options
linker options
preprocessor options
gcore (generate-core-file) command (GDB)
gcore command
GDB (GNU Debugger)
C preprocessor macros
command-line syntax
commands, alphabetical summary
commands, listed by category
aliases for other commands
examining data
examining the stack
file manipulation
frequently used commands
running a program
status inquiries
support facilities
Text User Interface commands
expressions
special expressions
files specified when doing debugging
info command
initialization files
program stoppers
set and show commands
source code URLs
Text User Interface (TUI)
user interfaces
gdb command
generate-core-file command (GDB)
generate-rss command (yum)
gensub function (gawk)
getconf command
ksh93
getline command (awk)
getopts command 2nd
getpwnam( ) function
getpwuid( ) function
gettext and dgettext functions
gettext command
source code URL
gettextize Linux command
ghostscript command
GhostScript, gs command
glob command (tcsh)
global command (ex)
GNU Mac OS X Public Archive (OSXGNU)
GNU utilities
Arch
escape sequences
gettext
sed
addresses for commands
options
regular expression extensions
troff (groff)
GNU/Linux, xiii
command summary
compilers
Fedora
Fedora distribution
finding commands
package management
goto command (tcsh)
gpatch Solaris command
gprof command
graph character class
grep command
pattern-matching metacharacters
quoting regular expressions
groff (GNU troff)
groff command
groupinfo command (yum)
groupinstall command (yum)
grouplist command (yum)
groupremove command (yum)
groups
file ownership for
id command
groups command
groupupdate command (yum)
gs command
gsub function (awk)
GUIs (Graphical User Interfaces)
python program with
shells vs.
gunzip command
gvimdiff command
gzcat command
gzip command

Previous Section < Day Day Up >


index_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 (help) command (GDB)
H command (sed)
h command (sed)
hackability of Subversion
handle command (GDB)
hangups, command immunity to
hash command
Bash
ksh
hashstat command (tcsh)
hbreak command (GDB)
head command
headers (Java code)
help
Emacs commands for
manpage keyword lookup
help command
Bash
GDB
svn
svnadmin
svnlook
here document
here string
hexadecimal constants (gawk)
hexadecimal digits, matched by xdigit character class
hexdump command
HFS filesystem, generating
hide command (ex)
hist command (ksh93) 2nd
history command
Bash
CVS
Korn shells
svnlook
tcsh
hostname command
hotcopy command (svnadmin)
hup command (tcsh)

Previous Section < Day Day Up >


index_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 (info) command (GDB)
i command (sed)
I/O processing commands (sed)
iconv command
id command
ident command (RCS)
if (shell keyword)
if command
awk
GDB
tcsh
if statements (tcsh)
igawk program 2nd
ignore command (GDB)
import command
CVS
svn
include statements (makefile)
indentation commands (Emacs)
basic
index function (awk)
indirect variables
info command
GDB 2nd
svn
svnlook
yum
InfoZIP format
init command (CVS)
initialization files (GDB)
inodes, reporting on
input mode (telnet)
input modes (terminal)
insert command (ex)
insert mode (vi)
Insight
inspect command (GDB)
install command (yum)
installation options (rpm)
installf Solaris command
instruction-level debuggers
int function (awk)
integer command (ksh)
interactive conversation
interactive use of shells
internationalization
gawk features
locale command
ISO 8601 date format
ISO 9660/Joliet/HFS filesystem, generating
ispell command 2nd

Previous Section < Day Day Up >


index_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]

jar Java command
jarsigner Java command
Java
command summary
compiling with gcc
java Java command
javac Java command
javadoc Java command
javah Java command
javap Java command
jdb Java command
job control
Bash and Korn shells
tcsh shell
jobID argument
tcsh job control commands
jobs command
Bash and Korn shells
tcsh 2nd
join command
ex
jump command (GDB)
jumps command (ex)

Previous Section < Day Day Up >


index_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)
keyboard shortcuts for editing
keylogin Solaris command
keylogout Solaris command
keys (authentication), generating for ssh
keytool Java command
keyword substitutions
CVS
RCS
example
Subversion
keywords
CVS
date keywords
expr
RCS, listed
Subversion 2nd
kill command
Bash and Korn shells
Emacs
GDB
tcsh shell 2nd
kserver command (CVS)
ksh (Korn shell)
arithmetic expressions
command execution
command history
line-edit mode
command syntax
commands, built-in
coprocesses
features differing from Bash and tcsh
features in common with Bash and tcsh
filename metacharacters
functions
history of
invoking
arguments
common options
job control
overview of features
Public Domain Korn shell (pdksh) 2nd
quoting
redirection syntax
restricted version (rksh)
setting restrictions on
syntax
special files
variables
arrays
built-in
discipline functions
other shell variables
special prompt settings
variable substitution
ksh88
ksh93
associative arrays
built-in mathematical functions
built-in shell variables
capabilities differing from ksh88

Previous Section < Day Day Up >


index_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 (list) command (GDB)
l command (sed)
lam Mac OS command
layout command (GDB)
ld command
ldd command
leave Mac OS command
left command (ex)
Lempel-Ziv (LZ77) coding
length function (awk)
less program
let command 2nd
lex command
lexical analysis programs, generating
library calls, tracing (ltrace)
library dependencies (GNU make)
limit command (tcsh)
line breaks, nroff/troff requests and
line information commands (sed)
line Solaris command
line-edit mode (command history)
lines
counting in files
formatting in files
numbering in files
reading from standard input
link command
/bin/sh, link to Bash
links, creating for files
lint command, secure (splint)
Linux
package management
list command
ex
GDB
svn
yum
list dynamic dependencies (ldd command)
list-dblogs command (svnadmin)
list-unused-dblogs command (svnadmin)
listing files
for current directory
in archives
to be executed
listusers Solaris command
ln command
load command (svnadmin)
loader (ld command)
loading and executing Java bytecode
local command (Bash)
local modes (terminal)
locale command
localinstall command (yum)
localization of strings
localupdate command (yum)
locate command
lockfile that can be used from shell scripts
locking/unlocking files
log command
CVS
svn
svnlook
tcsh
log function (awk)
logged-in users
displaying with users
listing with who
logger command
logging
checking in edited source code
GDB command output
rlog command
logging in
as another user
displaying login name
slogin command
logical operators
awk
Bash and ksh 2nd 3rd
tcsh
login command
CVS
ksh
tcsh
logname command
logout command
Bash
CVS
tcsh
look command
lower character class
lp command
lpq command
lpr command
lprm command
lpstat command
ls command
color options, setting
ls-F command (tcsh)
lshift function (gawk)
lstxns command (svnadmin)
ltrace Linux command
lynx Linux command

Previous Section < Day Day Up >


index_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]

M- commands (emacs)
m4 command
mac command
Mac OS X 10.4 (Tiger)
Mac OS X Developer Tools
Mac OS X, xiii
command summary
compilers
finding commands
ksh93 from AT&T Research
package management
mac2unix Linux command
machine faults, tracing
machine registers, accessing with GDB
Macintosh OS 9 files, converting to Unix
macro command (GDB)
macro commands (Emacs)
macros
definitions (makefile)
Emacs
listing names (ctags)
m4 processor
make utility
defining 2nd
exporting
internal
macro values
modifiers
text manipulation
with special handling
man
nroff/troff
vi editor
mail command
mail notification
Mail User Agent (MUA) program (mutt)
mailx command
make command
GDB
make utility
command-line syntax
options
macro modifiers
macros
defining
exporting
internal
macro values
overriding command line macros
text manipulation
with special handling
makefile lines
conditional input
special dependencies
special target names
versions other than GNU make
writing command lines
writing Makefile files
makecache command (yum)
makefile files, writing
makefile lines (make)
Makefile, tuned for target system
makefiles
overriding
man command
man macros
internal names
predefined strings
sample document output
mangled names (C++ and Objective C)
manpages
displaying
displaying command descriptions in
keyword lookup
manual pages, writing
man macros
internal names
summary of
overview of nroff/troff
sample document
strings predefined by man macros
map command (ex)
mark (Emacs)
mark command (ex)
marks command (ex)
match function (awk)
mathematical functions (ksh93)
md5sum Linux command
measurements for nroff/troff
mem command (GDB)
merge command
RCS
svn
merging changes to source code
mesg command
message authentication code (MAC)
message digests (PKCS#11), computing for files
Meta-key commands (Emacs) 2nd
metacharacters 2nd
Bash and Korn shell filenames
filenames vs. patterns
listed by Unix program
replacement pattern
searching and replacing in sed and ex
tcsh filenames
metadata, versioned
mkdir command
svn
mkexrc command (ex)
mkisofs command
mktemp command
mktime function (gawk)
mod_dav_svn plug-in (Subversion)
modes
Emacs editor
telnet
vi editor 2nd
modification timestamp for files, updating
monotone version control system
more command
mount command
Linux
Mac OS
Solaris
move command
ex
svn
moving directories and files
msgfmt command
MUA (Mail User Agent) program (mutt)
multiline input processing (sed)
multiple redirection
mutt Linux command
mv command

Previous Section < Day Day Up >


index_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 (next) command (GDB)
N command (sed)
n command (sed)
name demangling 2nd
name list (symbol table), printing for object files
name( ) function
nameref command (ksh93)
names
current Unix system name, printing
directories, printing
functions and macros, listing (ctags)
nano Mac OS command
native methods, implementing in Java
nawk command 2nd
nawk programming language
network layers, choice with Subversion
networks, securing remote connections cryptographically (ssh)
new command (ex)
newgrp command (tcsh)
newlines
word separators in Bash and ksh
word separators in tcsh
next command
awk
ex
GDB
nextfile command (awk)
nexti command (GDB)
ni (nexti) command (GDB)
nice command
tcsh
nl command
nm command
nohlsearch command (ex)
nohup command
Korn shells
tcsh
nosharedlibrary command (GDB)
NOT operator (!)
notify command (tcsh) 2nd
nroff/troff
command-line invocation
comments
eliminating .so requests
embedded formatting controls
escape sequences
input files, preprocessing
man macros
measurements, specifying
requests and macros
requests that cause a line break
special characters
null command 2nd
number command (ex)
number registers (man macros)
numbering lines in files
numbers
converting from one base to another
converting units of
prime factors
printing in sequence
nvi text editor

Previous Section < Day Day Up >


index_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]

object files
combining into single executable object module
generating
portable, translation into loadable message files
removing information from
Objective C programming language, compiling (gcc)
octal and hexadecimal constants (gawk)
octal dump (od) command
od (octal dump) command
onintr command (tcsh)
only command (ex)
ooffice Linux command
open command (ex)
Open Office office productivity suite
open-x11 Mac OS command
OpenSSH
scp command
sftp command
ssh command
OpenWindows Graphical Tools
Operating System/Application Binary Interface (OSABI)
operators
awk
Bash and ksh
tcsh shell
optimization around the network (Subversion)
Option key (Emacs commands)
or function (gawk)
OR operator
^ (bitwise exclusive OR)
| (bitwise OR) 2nd
|| (logical OR) 2nd 3rd
order-only prerequisites (GNU make dependencies)
OS X Package Manager
OSXGNU (GNU Mac OS X Public Archive)
output command (GDB)
output modes (terminal)
output processing commands (sed)
overloaded procedure names (C++ and Objective C)
ownership of files
changing

Previous Section < Day Day Up >


index_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 (print) command
GDB
sed
P command (sed)
package management
Linux
Debian Package Manager
Red Hat Package Manager
Red Hat Update Agent (up2date)
Yum (Yellowdog Updater Modified)
Mac OS X
Solaris
page command
paging commands
less
more
paging files
paragraph commands (Emacs)
parser (bison)
passwd command
passwd file
Bash and ksh
tcsh
user database stored in
passwords
changing
creating or changing
prompting for
paste command
pasting text in Emacs
patch command
path command (GDB)
pathchk command
pathnames
checking for acceptability
searching for files
stripping filenames from
pattern matching
awk
ex addresses
fgrep
metacharacters
listed by Unix program
replacement patterns
search patterns
searching and replacing (examples), in sed or ex
searching, examples of
pattern rules (makefile)
patterns, awk 2nd
simple pattern-action examples
pax command
pbcopy Mac OS command
pbpaste Mac OS command
PCMCIA memory cards, formatting
PDF (Portable Document Format) language
converting PostScript input file to
ghostscript command
gs command
pdksh (Public Domain Korn shell)
pdksh Linux command
perl command
Perl scripts, Debian package management
permissions (file), changing
pgawk (profiling gawk)
pico Mac OS command
PKCS#11 message authentication code
PKCS#11 message digest, computing for files
pkgadd Solaris command 2nd
pkgadm Solaris command
pkgask Solaris command
pkgchk Solaris command
pkginfo Solaris command
pkgmk Solaris command
pkgparam Solaris command
pkgproto Solaris command
pkgrm Solaris command
po (print-object) command (GDB)
point (Emacs)
popd command
Bash
tcsh
Portable Archive Exchange program (pax)
portable object files (.po files), translation into loadable message files
positional specifier (gawk)
POSIX standard
character classes, listed
make utility
Solaris systems, command versions
PostScript language
converting input file to PDF
ghostscript command
gs command
pr command
precision (format specifiers for printf and sprintf)
precompiled packages from Sun Microsystems
predefined shell variables
Bash and ksh
tcsh
sample .tcshrc file
prerequisites (make utility)
preserve command (ex)
previous command (ex)
prime factors
print character class
print command
awk
output redirection
ex
GDB
value history
ksh
print-object command (GDB)
printenv command
tcsh
printf command
awk
output redirection
Bash and Korn shells
GDB
printing
all lines that begin with a string
archive files
banners
BSD commands
cancelling print requests 2nd
current system name
environment variable values
file creation mode mask
files
lines specified
sending files to printer with lp
sending files to printer with lpr
strings, using specified formats
system configuration variables
system usage information
System V commands
terminal device name
to standard output
printing commands
cancel
lp
lpq, checking spool queue
lpr
lprm, removing jobs from the queue
lpstat, printing queue status
procedures, awk
processes
active, reports on
ps command 2nd
core images of
sending signal or resetting priority
terminating IDs
profile data, displaying
profiling in gawk
programmable completion (Bash) 2nd
programming commands
programming languages
compiling with gcc
GDB support for
source files, listing function and macro names
programming lint (splint command)
programs
GDB commands for running
getting description of
prompts, xvi
GDB
special prompt strings, Bash and Korn shells
tcsh
propdel command (svn)
propedit command (svn)
properties, Subversion files
propget command
svn
svnlook
proplist command
svn
svnlook
propset command (svn)
provides command (yum)
ps (process status) command
Linux
Mac OS
Solaris
PS1-PS4 variables
pserver command (CVS)
pstopdf Mac OS command
ptype command (GDB)
Public Domain Korn Shell (pdksh)
punct character class
pushd command
Bash
tcsh
put command (ex)
putting and yanking commands
Emacs
sed
vi 2nd
pwd (print working directory) command
Bash and ksh
GDB
python command
pythonw Mac OS command

Previous Section < Day Day Up >


index_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)
query options (rpm)
queued jobs
listing jobs created by at command
removing
quit command
ex
GDB
quoting
bash and ksh shells
tcsh shell

Previous Section < Day Day Up >


index_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 (run) command (GDB)
r command
ksh
sed
R command (sed)
rand function (awk)
ranges, matching
rannotate command (CVS)
rbreak command (GDB)
rcp command
RCS (Revision Control System) 2nd
basic operation
check out with locking model
commands, overview
commands, summarized alphabetically
date and time of check-in
keyword substitution
example
keywords, listed
options and environment variables
revision numbers
revision states
rcs command
svn
rcsclean command (RCS)
rcsdiff command (RCS) 2nd
rcsfreeze command (RCS)
RCSINIT environment variable
rcsmerge command (RCS)
rdiff command (CVS)
read command
Bash and Korn shells
ex
reading email messages
readline library
readonly command
recover command
ex editor
svnadmin
Red Hat Network Notification Tool (rhn-applet)
redirect command (ksh93)
redirections
awk, print and printf output
Bash and ksh forms for
tcsh 2nd
redo command (ex)
referencing arrays
refresh command (GDB)
region commands (Emacs)
regular expressions
egrep command
GNU sed, extended
grep command
lexical analysis program
metacharacters 2nd
not supported by fgrep
search pattern metacharacters
searching, examples of
sed command addresses
rehash command (tcsh)
relational operators
awk
Bash and ksh
tcsh
release command (CVS)
releases, Subversion
remote (r) commands
remote file transfer
Remote Method Invocation compiler for Java (rmic)
remote object registry (Java)
remote systems, copying files between
scp
removable media
checking if inserted
ejecting
remove command
CVS
yum
removef Solaris command
removing directories (rmdir)
removing files
rm command
srm command
rename Linux command
renaming directories and files
repeat command (tcsh)
replacement patterns
metacharacters
Unix program metacharacters
replacing files in archives
replacing text in sed or ex, examples of
repository
access to (svnserve tool)
administration (svnadmin tool)
options
subcommands
converting from CVS to Subversion
examining (svnlook tool)
options
subcommands
filtering files from dump (svndumpfilter)
requests (nroff/troff)
causing a line break
useful requests
reset command
resize command (ex)
resolved command (svn)
restricted shells
return command
awk
Bash and Korn shells
GDB
reverse-search command (GDB)
revert command (svn)
revision control systems
CVS
RCS
Subversion
rewind command (ex)
RFC 1123 time format
RFC 822 time format
rhn-applet
right command (ex)
rksh Solaris command
rlog command
CVS
RCS 2nd
rlogin command
rm command
rmdir command
RMI (remote method invocation)
compiler
rmic Java command
rmid Java command
rmiregistry Java command
rmtxns command (svnadmin)
RPM (Red Hat Package Manager) 2nd
package concepts
package names
rpm command
rpmbuild command
rpm command
database rebuild options
downloading packages off the Internet
examples
FTP/HTTP options
general options
information selection options
install, upgrade, and freshen options
miscellaneous options
package selection options
query options
signature check options
uninstall options
verify options
rpmbuild command
RSA or DSA identities, adding to authentication agent
rsh command 2nd
rshift function (gawk)
rsync command
rtag command (CVS)
rules (GNU make)
run command (GDB)
running programs (GDB commands)
rwatch command (GDB)

Previous Section < Day Day Up >


index_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 (step) command (GDB)
s command (sed)
Samba software suite
sandbox 2nd
dot files in CVS
say command (Mac OS)
sbnext command (ex)
sbuffer command (ex)
SCCS (Source Code Control System)
check out with locking model
sched command (tcsh)
scp (secure copy) command
script command
scripts
Debian package management
sdiff command
search command
GDB
yum
search commands
egrep
Emacs
fgrep
find
grep
locate
look
slocate
strings
vi
search patterns
metacharacters
Unix metacharacters
searching
by pattern matching
in vi editor
regular expressions, using
search-and-replace examples, sed and ex
secret keys
decrypting
deleting
encrypting
section command (GDB)
secure copy (scp) command
secure ftp (sftp) command
secure network services
computing PKCS#11 MAC for given files
decrypting secret keys in
deleting secret keys in
encrypt Solaris command
encrypting secret key
Secure Shell (SSH)
ssh command
ssh-add command
ssh-agent command
sed editor 2nd
command syntax
GNU sed extended regular expressions
pattern addressing
command-line syntax
GNU sed options
standard options
commands
summary, listed alphabetically
commands by category
basic editing
branching
input/output processing
line information
multiline input processing
yanking and putting
operation
pattern-matching metacharacters
search-and-replace examples
typical uses of
select (shell keyword)
select-frame command (GDB)
selection states (Debian packages)
sending email messages
seq Linux command
server command (CVS)
server environment variables (CVS)
sessions
control by shell
recording
set and show commands (GDB)
annotate
architecture
args
auto-solib-add
auto-solib-limit
backtrace
breakpoint
can-use-hw-watchpoints
case-sensitive
coerce-float-to-double
commands
complaints
confirm
convenience
copying
cp-abi
debug-file-directory
demangle-style
directories
disassembly-flavor
editing
environment
exec-done-display
follow-fork-mode
gnutarget
height
history
input-radix
language
listsize
logging
max-user-cal-depth
opaque-type-resolution
osabi
output radix
overload-resolution
pagination
paths
print
prompt
radix
scheduler-locking
solib-absolute-prefix
solib-search-path
step mode
stop-on-solib-events
symbol-reloading
tui
values
variable
verbose
version
warranty
watchdog
width
write
set command
Bash and Korn shells
ex
GDB
tcsh
setenv command (tcsh)
setlog command (svnadmin)
setpgrp Solaris command
settc command (tcsh)
setty command (tcsh)
sftp (secure ftp) command
sh command
sh, invoking Bash as
SHA1 160-bit checksums
sha1sum Linux command
shar Mac OS command
share command (GDB)
shared object libraries, tracing calls into/out of
sharedlibrary command (GDB)
shell archive (shar) command
shell characters, special (Emacs)
shell command
ex
GDB
shell programming commands
shell scripts
Debian package management
for background processes
lockfile used from
reading from terminal
shells
choosing your shell
commands
csh command
differing features, Bash, ksh, and tcsh
introduction to
invoking Bash and Korn shells
restricted
source code, URLs for
tcsh shell
types (flavors) of
uses of
customizing Unix session
interactive use
shift command
Bash and Korn shells
tcsh
shlock Mac OS command
shopt command (Bash)
show command (GDB)
shred Linux command
si (stepi) command (GDB)
signal command (GDB)
signals, tracing
signature verification for packages
signature-checking options (rpm)
silent command (GDB)
sin function (awk)
size command
skill Linux command
sleep command
sleep command (ksh93)
slocate Linux command
slogin command
snext command (ex)
snice Linux command
sockets, use with gawk coprocesses
soelim command
software, building
Solaris
command summary
finding commands
package management
command summary
POSIX standard, programs compliant with
Solaris 10, xiii
compilers
sort command
sorting files
joining lines of sorted files
removing duplicate lines
sotruss Solaris command
source code
awk versions and GNU gettext, URLs
building software from 2nd
management
CVS (Concurrent Versions System)
RCS (Revision Control System)
Subversion
systems for Unix
terminology
usage models for systems
source command
Bash
ex
GDB
tcsh
source-level debuggers
space character class
spaces
expanding tab characters into
word separators in Bash and ksh
word separators in tcsh
special characters
tcsh
troff
spell command
splint Linux command
split command
ex
split function (awk)
splitting files
sprevious command (ex)
sprintf function (awk)
format specifiers
sqrt function (awk)
srand function (awk)
srm Mac OS command
ssh (Secure Shell) command
ssh-add command
ssh-agent command
ssh-keygen command
stack examination commands (GDB)
standard input, output, and error
GNU sed
STDIN, copying 2nd
STDOUT, printing to
startup files (tcsh)
state, RCS revisions
status command
CVS
svn
status inquiry commands (GDB)
step command (GDB)
mode, setting
stepi command (GDB)
stickiness, CVS files
stop command
ex
Korn shells
tcsh 2nd
stopping commands (Emacs)
storage commands
strace Linux command
stream editor
strftime function (gawk)
string searches with apropos
strings
comparing and searching with expr
localizing
printing, using specified formats
substituting characters in
strings command
strip command
strtonum function (gawk) 2nd
stty command
su command
sub function (awk)
subcommands (CVS), common synonyms
substitute command (ex)
substitutions, PS1-PS4 variables
substr function (awk)
Subversion 2nd
basic version control operations
converting repository from CVS
"copy, modify, merge" model
file properties, special
improvements on CVS design
obtaining
features in next version
releases
source code
svn (command line client)
options
subcommands
svnadmin (repository administration)
options
subcommands
svndumpfilter command
svnlook (repository, examining)
options
subcommands
svnserve command
svnversion command
using for version control
suffix rules (makefile)
Sun Desktop commands
suspend command
Bash and Korn shells
ex
tcsh
sview command (ex)
svn (Subversion command line client)
options
subcommands
svnadmin (Subversion repository administration)
options
subcommands
svndumpfilter command (Subversion)
svnlook (Subversion repository, examining)
options
subcommands
svnserve (Subversion repository access)
SVR4 (System V Release 4)
switch command
svn
tcsh
symbol file
symbol tables (name list), printing for files
symbol-file command (GDB)
synaptic Linux command 2nd
synchronizing files across a network connection 2nd
system calls, tracing
strace Linux command
system configuration variables, printing
system dictionary, adding to
system function (awk)
system name, current
system status commands
system usage information
printing
timex (Solaris) command
w command
System V
Bourne shell
printing commands
Release 4 (SVR4)
systime function (gawk)

Previous Section < Day Day Up >


index_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
sed
T command (sed)
tab characters, xvi
converting spaces to
expanding to spaces
tabs
word separators in Bash and ksh
tabs, word separators in tcsh
tag command (CVS)
tag command (ex)
tag files, creating with ctags
tagging improvements, Subversion
tags command (ex)
tags, naming source code files
tail command
talk command
TAO (track-at-once) mode
tape files, copying/restoring 2nd
tar command
targets, GNU make
special names
tbreak command (GDB)
tcatch command (GDB)
tcsh (Tenex C shell) 2nd
arithmetic
command history
command substitution
history modifiers
special aliases
word substitution
command-line manipulation
completion
editing the command line
commands, built-in
expressions
@ command examples
if and while statement examples
operators
features differing from Bash and ksh
features in common with Bash and ksh
filename metacharacters
invocation, options and arguments
job control
prompts
quoting
special characters
special files
syntax
redirection
variables
environment variables
modifiers
predefined shell variables
sample .tcshrc file
variable substitution
tcsh command
tee command
telltc command (tcsh)
telnet command
template file of C #define statements
temporary filename, generating
temporary files (RCS)
terminal emulators, ANSI/VT100
terminal sessions, recording (script)
terminals
clearing displays
clearing with reset
device name, printing
setting I/O options for current device
setting modes
terminating process IDs
termination status for background processes
termname command (tcsh)
test command 2nd
text
converting spaces into tabs
expanding tabs into spaces
formatting with fmt command
manipulation with make utility
text editors
ed
Emacs vs. vi
nano
pico
regular expression delimiters
Unix metacharacters
"text mode" browser (lynx)
text processing commands
text to speech synthesizer (say)
Text User Interface (TUI) 2nd
GDB commands for
thbreak command (GDB)
thread command (GDB)
time command
Bash and Korn shells
tcsh
time zones
times command
times command (ksh93)
timestamps, RCS
timex Solaris command
tolower function (awk)
touch command
toupper function (awk)
tr command
tracing system calls (strace)
track-at-once (TAO) mode
transposing words (sed)
transposition commands (Emacs)
trap command
tree command (svnlook)
trigger scriptlets
troff program
command-line invocation
eliminating .so requests
escape sequences
preprocessing of input files
special characters
troff command
true command 2nd
truss Solaris command
tset command
tty command
GDB
TUI (Text User Interface) 2nd
GDB commands for
tui command (GDB)
type command
Bash
ksh
type-safe linkage
typeset command
-A (creating associative arrays)
-n (indirect variable referencing)

Previous Section < Day Day Up >


index_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]

u (until) command (GDB)
ulimit command
umask command
Bash and Korn shells
tcsh
umount command
Linux
Mac OS
Solaris
unabbreviate command (ex)
unalias command
Bash and Korn shells
tcsh
uname command
uncomplete command (tcsh)
uncompressing files
undisplay command (GDB)
undo command (ex)
undoing commands (Emacs)
unedit command (CVS)
unexpand command
unhash command (tcsh)
unhide command (ex)
uninstall options (rpm)
uniq command
units command
units of measurements (nroff/troff)
Unix
summary of common commands
versions of
unix2dos command
unlimit command (tcsh)
unmap command (ex)
unset command
GDB
tcsh
unsetenv command (tcsh)
until (shell keyword)
until command (GDB)
unzip command
up command (GDB)
up-silently command (GDB)
up2date (Red Hat Update Agent) 2nd
update command
CVS
GDB
svn
yum
upgrade command (yum)
upgrade options (rpm)
upper character class
uptime command
URLs
Arch (source code management system)
aspell
autoconf
automake
awk source code and GNU gettext
awka
Bash 2nd
Bash completion
Bash Debugger
Bash source code
Bash source code patches
bc language (and compiler)
bison
bzip
cdrdao (Sourceforge)
Codeville (version control system)
CSSC (free clone of SCCS)
ctags
CUPS (Common Unix Printing System)
curl
ddd (Data Display Debugger)
diff
ed
Emacs editor
Figlet
Fink Commander
Fink project
flex
gawk
gcc
GCC and precompiled packages (Sun)
GDB (GNU Debugger)
gettext 2nd
gettextize
gprof (GNU)
groff (GNU troff)
gs (ghostscript)
gzip
info
Insight debugger
ispell
Korn shell
Korn shell, Public Domain (pdksh) 2nd
ksh93 source code
less
lynx (text mode) browser
m4 (macro processor)
make program
mawk
Monotone (version control system)
mutt (Mail User Agent program)
nano editor
nroff/troff
Open Office
OpenSSH
OSXGNU (GNU Mac OS X Public Archive)
patch
perl
python
rsync (Samba)
Samba
screen
shells, source code
slocate
Solaris patches, support
Solaris, Sun freeware
splint
srm (Sourceforge)
Subversion project site
sudo
tar
tcsh source code
tcshrc
troff
vim editor 2nd
wget
xgettext
Z shell source code
ZIP
ZIP (unzip)
usage information
disk blocks used by directory and subdirectories
timex (Solaris) command
w command
user interfaces (GDB)
Text User Interface (TUI)
users
changing information for with chpass
displaying data about
displaying group membership
id command
information on those logged in
listing
logged-in, displaying list
username for user ID, printing
users command
UTC (Coordinated Universal Time)
uudecode command
uuid command (svnlook)

Previous Section < Day Day Up >


index_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
sed
vacation Solaris command
value history
variable substitution
variables
awk
assignment
built-in
Bash and Korn shells
arrays
built-in
discipline functions (ksh93)
other
special prompt settings
convenience variables (GDB)
CVSROOT directory
environment variables
internal variables
shell variables in files
setting, Bash and Korn shells
system configuration, printing
tcsh shell
command-line manipulation
environment variables
predefined shell variables
prompt variable, formatting
sample .tcshrc file
variable modifiers
variable substitution
verify command (svnadmin)
verify options (rpm)
version command
CVS
ex
version control systems
CVS
for Unix
other
RCS
Subversion
version history, true history in Subversion
versioned metadata
versions of Unix
vi editor 2nd
bindings, compared to Emacs bindings
command mode
command syntax
command-line syntax
options
commands
configuration
.exrc file
.exrc file (example)
:set command
:set command options
edit commands
changing and deleting text
copying and moving text
ex commands in
insert mode
interacting with the system
line-edit mode, Bash and ksh
macros
miscellaneous commands
movement commands
character
line numbering
lines
marking position
screens
searching
text
multiple files, accessing
operating modes
pattern-matching metacharacters
saving and exiting
starting ex from
status line commands
tcsh command-line editing mode
user-defined commands, characters for
window commands
view command
ex
vile text editor
vim editor
command-line options
evim command
vim command
vimdiff command
visual mode
vimdiff command
visual command (ex)
volcheck Solaris command
vpath statements (makefile)
vsplit command (ex)
VT100 terminal emulation, enabling

Previous Section < Day Day Up >


index_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
sed
W command (sed)
wait command
Bash and Korn shells
tcsh
wall command (ex)
watch command
CVS
GDB
Linux
watchers command (CVS)
watchlog command (tcsh)
watchpoints
WAV format, converting CDDA to
wc (word count) command
wget Linux command 2nd
whatis command
GDB
whatis database, searching with apropos command
whatprovides command (yum)
whence command (ksh)
where command
GDB 2nd
tcsh
which command
tcsh
while command
awk
Bash and Korn shells
GDB
tcsh 2nd
whitespace
converting spaces into tabs (unexpand)
expanding tabs into spaces
space character class
who command
whoami command
whocalls Solaris command
width (format specifiers)
window (Emacs)
window commands (Emacs)
window size, setting for terminal
Windows systems, serving Unix filesystems to
winheight command (GDB)
wnext command (ex)
word character class
word count (wc) command
word separators
Bash and ksh
tcsh
word substitution (tcsh)
word-abbreviation commands (Emacs)
wordlist files
words, automatic completion
in Bash
in tcsh
wq command (ex)
wqall command (ex)
write command (ex)
writing to standard output

Previous Section < Day Day Up >


index_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
GDB
sed
X command (ex)
X11 applications under Mac OS X
xargs command
Xcode Tools package
xdigit character class
xgettext command
xit command (ex)
xmlto Linux command
xor function (gawk)

Previous Section < Day Day Up >


index_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)
y editing operator (vi) 2nd
yacc command 2nd
yank command
Emacs
ex
yanking and putting commands (sed)
youngest command (svnlook)
Yum (Yellowdog Updater Modified)
command summary
yum command 2nd

Previous Section < Day Day Up >


index_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
zip command
ZIP format archives, extracting or printing information about
zipinfo command
zsh (Z shell)

Previous Section < Day Day Up >